docs get started
Rate limits
429, Retry-After, daily caps, and async runs.
Each API key may make 120 requests per minute. The same cap is kept in the database, so it holds across processes. MCP tool calls on one HTTP request count as one hit against that key. Requests without a key, including signup, the plan list, and a rejected MCP credential, share 120 per minute per network. Provider callbacks and GET /health are not counted. HTTP 429 rate_limited includes Retry-After in seconds. Wait, then retry. A 429 is not a failed search.
Daily credit caps
A key can carry daily_cap_credits, and so can a customer. When the spend for the UTC day reaches either cap, paid calls return 402 daily_credit_cap_reached with details.cap (key or customer) and resets_at, the next UTC midnight. Free calls keep working. A key created by a capped key cannot have a higher cap. Without a cap, the balance is the only ceiling.
Async runs
POST /v1/runs returns 202 at once with the run and its plan. The run works in the background for up to 3 hours. Listen for run.completed on a webhook endpoint, or poll GET /v1/runs/{run_id}. Over MCP, get_search_results with wait_seconds holds the call open until there is news, so the agent does not have to poll.
Search pages are taken one at a time from a fair queue per workspace, so one large run does not starve another workspace. At most 5 upstream calls run at once, with 10 waiting. When the data source is busy, a run moves to waiting_for_quota and resumes on its own; a synchronous call returns upstream_busy with Retry-After.
Upstream busy
upstream_busy (HTTP 429, 502, or 503) means the data source is busy, not that your key is going too fast. Nothing was charged. Retry after Retry-After. upstream_error (502) means the source returned something unusable; retry later.
What it costs
Rate limits are free. A busy page that is retried is charged once, when it arrives.
Reference: Errors and the RateLimited response in the API reference.