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_left shows 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_matches is never more than 10,000. 10,000 means 10,000 or more.
  • partial is true when more than 15,000 pages match. The results then come from only a subset of matching pages.
  • What to do when partial is 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_usage show 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, and ping) 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_left through 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.