Rate limits & quotas

Limits come in two flavours: a rate limit that smooths burst traffic, and a monthly quota that caps total volume. Both are counted per account: every clf_ key you hold, and any OAuth client signed in as you, draws from the same counters. Creating more keys does not raise your limits.

Rate limits

The rate limiter counts requests per Clarifo account in fixed windows — each calendar second and each calendar minute (UTC) — and the count is shared by every server handling your traffic. The limits are the same for every plan:

Exceeding either window returns HTTP 429 with a Retry-After header: 1 (seconds) for the per-second window, 60 for the per-minute window.

{
  "error": "Rate limit exceeded: max 10 req/sec",
  "status_code": 429,
  "path": "/api/v1/data/companies/screen",
  "correlation_id": "6f1c2b0e-8a4d-4c3e-9b7a-2d5e1f0a9c11"
}

Monthly quota

Pro includes 10,000 Data API requests per month per account, shared by all of your keys. clf_test_… keys additionally have their own cap of 1,000 requests per month per key, inside the same account pool, so a runaway development script cannot spend your production volume. Once the account (or a test key) reaches its limit, requests return HTTP 429:

{
  "error": "Monthly quota exceeded (10000 requests per account). Upgrade your plan or wait until next month.",
  "status_code": 429,
  "path": "/api/v1/data/filings/search",
  "correlation_id": "6f1c2b0e-8a4d-4c3e-9b7a-2d5e1f0a9c11"
}

The quota response carries X-Clarifo-Quota-Used (requests counted this month) and X-Clarifo-Quota-Limit (the cap). Settings → API keys shows the account total. Counters reset at the start of each calendar month (UTC). Email notifications go to the account owner at 80 %, 95 % and 100 % of the account quota.

Need more volume or throughput? Enterprise contracts size the quota to your use case — email support@clarifo.com.

Counting model

Every request that reaches an endpoint counts against the account's quota: successful responses, tool-level misses (HTTP 200 with an error field) and 500 server errors alike. Requests rejected before that point do not count toward the monthly quota: authentication failures (401), subscription failures (402), rate-limit and quota rejections (429) and validation errors (400, 422). The per-second and per-minute windows above are counted earlier, before the request is validated, so a rejected request still uses a slot in those windows. A replayed response for a repeated Idempotency-Key does not count either.

This quota is separate from the fair-use allowance of the MCP server.