Documentation / Getting Started / How the API Handles Requests
How the API Handles Requests
Understand why a request is rejected, whether it counts toward your daily limit, and when to try again.
These rules apply to the API and to the MCP server. There is no queue. A call that cannot run immediately is rejected. Send it again.
Your team members' calls count toward your account usage and share the same limits.
One search at a time
Each news_ and prospects_ tool is an index
search. Only one index search runs at a time for an account.
- A search sent while another is running is rejected immediately with HTTP
429 and the error
one_at_a_time. The error message is "An index search is running for this account. Only one search can run at a time. Try again in a few seconds." - The rejected search does not count toward your daily search limit.
- What to do: wait a few seconds and send it again. Do not send index searches in parallel.
One change at a time
A call that changes data, for example
campaigns_update, runs
only when no other change is running for the account.
- A change sent while another change is running is rejected immediately with HTTP
429 and the error
one_at_a_time. The error message is "Another change is running for this account. Only one change can run at a time. Send the call again in a few seconds." - The rejected call does not count toward your daily limit and is not queued.
- What to do: send the call again after a few seconds.
A search that takes too long
Each search statement stops after 10 seconds.
- A stopped search returns HTTP 422 and the error
search_stopped. The error message explains how to make the search more specific. - A stopped search counts as 1 search.
- A search with a vector and with words or conditions sends 2 statements: first a count, then the search. Each statement has its own 10-second limit.
- What to do: do not send the same search again. Narrow it with more specific words, a higher minimum PR, or a shorter date range.
Daily counts
- An accepted call counts as 1 call toward the daily limit.
- A rejected call does not count toward the daily limit. A stopped search does count.
- All index searches in an account share one daily count. Each other tool has its own daily count.
- The counts reset at 04:00 New York time.
account_calls_leftshows the calls left today.
The limits for each plan are on Usage and Daily Limits.
Large result counts
These rules apply to a search with a vector (semantic similarity), for
example with news_search.
total_matchesis never more than 10,000. 10,000 means 10,000 or more.partialis true when more than 15,000 pages match. The results then come from only a subset of matching pages.- What to do when
partialis true: make the search more specific.
Strict fields
- Unknown fields, empty text, and out-of-range values are rejected. The error names the field.
- Search tools do not apply values you did not send, except
results_limit, which defaults to 100.
The request log
- Each request with a valid token creates an entry in the account
request log. The Usage page and
account_usageshow these entries. - A rejected request also creates an entry, with its status, for example
403 or 404. The calls that an MCP client makes to connect
(
initialize,tools/list, andping) create log entries but do not count toward daily usage. - These requests do not create log entries: a request rejected with HTTP 429 because
another search or change is running, a call of
account_calls_leftthrough the API or MCP, and a request with no valid token (HTTP 401).
Server errors
If the server cannot save a change, it returns HTTP 500 and the
error db_error. No data was changed.