Rate limits and job credits

Request rate

Each plan allows a number of API requests in any 60-second window. The window counts every request from your account across all of its keys.

A request over the limit gets 429 with code rate_limited and a Retry-After header in seconds. A refused request does not use the window or any jobs. A request the API accepts uses the window even if it then fails with a 4xx or 5xx.

Monthly jobs

Your plan sets how many records you can receive in a calendar month (UTC). The month resets at 00:00 UTC on the first day of the next month. Only successful responses count:

• each job or company in a response counts as one, including a job you fetched before;
• each event from /v1/jobs/changes counts as one;
• /v1/jobs/count, /v1/usage/requests and /v1/usage/analytics return no records and use no jobs;
• errors, redirects and empty pages use no jobs.

When a successful response would go past the allowance, the API sends 429 with code data_limit_exceeded and no data. The free plan is 1,000 jobs a month; paid plans run from 5,000 to 500,000. See pricing.

Monthly requests

Each plan also allows a number of API requests a month: half as many as its jobs, so 250 on the free plan, 2,500 on the 5,000-job plan and up to 250,000 on the 500,000-job plan. Every API call counts as one request, however many jobs it returns, including errors, redirects and /v1/usage calls. A call refused with 401 (missing or invalid key) or 429 does not count. Unused requests carry over for 12 months, oldest month first.

Through the MCP server, each call to search_jobs, get_job or count_jobs is one request, however many jobs or pages it returns, including a search delivered as a file. list_fields, get_usage, set_confirmation_level, read_file and search_docs use none, so you can always check your usage. A call that starts with one request left finishes all its pages. Over MCP the refusal comes back as a tool error with http_status 429 and code rate_limited.

Once the month’s requests are used, calls get 429 with code rate_limited and the message “The monthly API request allowance has been reached”, before any work is done. Retry-After gives the seconds until the first of next month (UTC).

Headers on each response

Page sizes

Text filters take 1 to 200 characters. Cursor rules are on the pagination page.

Staying under the limits

• Run /v1/jobs/count first: it tells you how many jobs a query would use, for free.
• Use the largest page size you can (250 for jobs) to save requests.
• Keep in sync with /v1/jobs/changes instead of re-reading whole lists; see the ingestion strategy.
• On 429, wait for Retry-After, then retry the same request.