Rate Limits

The v3 API limits how many requests each workspace can make in a window of time. The limit protects your workspace and everyone else's from a runaway loop; an integration that behaves normally rarely meets it.

Budgets

Every workspace has two budgets, counted separately:

Budget	Default limit	What it covers
standard	1,000 requests per hour	Every request that reads or writes workspace data — which is almost all of them.
cheap	10,000 requests per hour	Requests that cost almost nothing to answer, listed below.

The limits apply to the workspace, not to the key: all of a workspace's keys, and its MCP connections, share the same two budgets.

Windows are fixed, not sliding. Each hour-long window starts on the hour, UTC, and a new window starts with a full budget.

What Uses the Cheap Budget

Surface	Requests
REST	GET /v3/auth/test; polling a draft commit with GET /v3/drafts/{key}/commit; the schema and authoring guide routes under /v3/schema/.
MCP	The protocol itself — initialize, ping, tools/list, resources/list, resources/read, prompts/list and notifications; and the tools get_authoring_guide, get_template_schema, list_content_types, describe_content_type, list_condition_operators, list_due_date_scenarios, validate_template, validate_template_draft and get_commit_status.

Everything else is charged to the standard budget. An MCP request that batches several messages is one request, charged to cheap only if every message in it is cheap.

Rate Limit Headers

Every response to an authenticated request carries four headers describing the budget it was charged to:

Header	Description
X-RateLimit-Bucket	Which budget this request was charged to: standard or cheap.
X-RateLimit-Limit	The size of that budget for the window.
X-RateLimit-Remaining	How many requests are left in that budget for the window.
X-RateLimit-Reset	When the window ends and the budget refills, as Unix time in seconds.

X-RateLimit-Bucket: standard
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1790503200

Read X-RateLimit-Bucket alongside the other three. The two budgets have different sizes, so without it two consecutive responses can appear to disagree about your limit.

When You Exceed a Budget

The request is refused with 429 Too Many Requests, a Retry-After header giving the seconds until the window ends, and the error code RATE_LIMIT_EXCEEDED:

HTTP/1.1 429 Too Many Requests
Retry-After: 1260
X-RateLimit-Bucket: standard
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790503200

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. The standard budget is 1000 requests per window and this workspace has spent it. Retry in 1260 seconds.",
    "requestId": "req_2e9d4a7c1b3f48e0a6c5d8b1f7e2a094",
    "retryAfterSeconds": 1260
  }
}

Every request before the window ends is refused in the same way, so retrying in a loop does not help — wait for Retry-After. Running out of one budget does not affect the other: when standard is spent, cheap requests still succeed.

The MCP server returns the same refusal inside its MCP response, with retryAfterSeconds in the error, and also sends the four headers. See How the MCP Server Works.

Invalid Keys

Separately from the workspace budgets, requests with an invalid, revoked or expired key are throttled by source address: after 20 such refusals from one address within a minute, further requests from that address are answered 429 until the minute is up. This stops a misconfigured integration from retrying a bad key indefinitely.

Staying Within the Limits

• Use pageSize=100 when reading whole lists. It is one request per hundred items instead of two.
• Use webhooks instead of polling. A webhook tells you when something changes; polling asks every few minutes whether anything has.
• Batch writes where the API allows it — setting several task fields in one request, or creating Data Set records in bulk.
• Watch X-RateLimit-Remaining and slow down as it approaches zero, rather than waiting for a 429.
• Back off on 429 by waiting Retry-After seconds before the next request.

Related Pages

• Errors — the error body and the other codes.
• Idempotency — replays count against the budget too.
• Webhooks — the alternative to polling.
• Pagination — fewer, larger pages.