Skip to main content
Two meters govern every request: how fast you can call (rate) and how much data you can pull (credits). Each has its own headers and error code.

​
Rate limits

Each API key allows 15 requests per second. Exceed it and requests return 429 RATE_LIMITED; wait for the one-second window to reset, then retry.

​
Headers

​
Notes

  • Limits apply per API key, shared across your team; parallel jobs draw on the same budget.
  • Bulk endpoints (up to 50 items per request) cut your request volume.

​
Credit usage

Data is metered in credits per billing period. Every reference page states its exact cost in a note at the top.

​
How credits are charged

Whether a call costs credits comes down to whether it manages configuration or retrieves data, and, for data, how much it returns. Every reference page states the exact figure in a “Costs …” note at the top of its description; treat that as the source of truth. Free (no credits): Charged (data retrieval):
  • Enrichment and by-ID lookups are charged per matched result, so a miss costs nothing.
  • Paginated feeds are charged per request, per page.
  • List results and saved-search results are charged per result returned.
  • Premium data (such as verified email and revenue signals) costs more per result.
Creating or editing a list or saved search never costs credits; you pay only when you pull data. When credits run out, requests return 402 OUT_OF_CREDITS and stop until the allowance resets.

​
Headers

The X-CreditLimit-* headers appear on 402 OUT_OF_CREDITS and 429 responses:

​
Daily spending limit

Your monthly budget is one ceiling; a daily limit is a second, tighter one that you set yourself. A workspace admin turns it on under Settings → API Console, and from then on your organization’s API calls stop for the rest of the day once the day’s charges reach it. The count clears at 00:00 UTC, so a bug that loops costs one day’s limit rather than the month’s budget. No limit is set by default, and setting one is the only way it applies — nothing changes for an organization that hasn’t.
The limit covers API calls only. Specter Agent runs and MCP tool calls draw on the same credit budget and are not subject to it, so they keep spending after the limit is reached and their usage is not counted in daily_used. Cap those in the Agent and MCP settings instead.
Once the limit is reached, requests return 402 DAILY_CREDIT_CAP_REACHED. That is a different code from OUT_OF_CREDITS because the remedy is different: no top-up is needed, the limit simply clears at midnight UTC. Raising or removing it is an admin action in the API console — the API cannot change it, deliberately, so a runaway client can’t lift its own ceiling. Read where you stand with GET /organization/credits, which reports daily_cap, daily_used and daily_remaining (daily_cap is 0 when no limit is set). The call is free and stays readable when the limit is reached.

​
Headers

These accompany every response while a daily limit is set, and are the headers a 402 DAILY_CREDIT_CAP_REACHED carries:

​
Best practices

  • Track credit usage client-side (you know each call’s cost up front) so a 402 never surprises you mid-run; X-CreditLimit-Reset tells you when it renews.
  • Set a daily limit sized to a normal day’s work, not a round number. A paginated pull of per-result data bills a page at a time, so a limit of a few thousand can be reached in minutes.
  • Treat 402 DAILY_CREDIT_CAP_REACHED as “stop until tomorrow”, not as a reason to retry: X-CreditLimit-Daily-Reset gives the wait in seconds.
  • Use bulk endpoints to cut both rate and credit usage.
  • Use the free management and Account endpoints for dashboards and monitoring.
  • Expect empty results (not errors) when data isn’t available.