> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> How Croma Legal API quotas are bucketed and reported.

## Per-organization buckets

Rate limits are enforced **per organization**, not per key. Every key issued
to the same organization shares one bucket, and calls made through the
[MCP server](/legal/mcp-server) draw from that same bucket, so adding keys or
clients doesn't multiply your quota.

| Bucket      | Limit                 | Endpoints                                                                                             |
| ----------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
| Default     | 1,000 requests / 24 h | Every `/v1/*` endpoint and every MCP tool call.                                                       |
| Job polling | 600 / minute          | [`GET /jobs/:id`](/legal/exports). Its own bucket, so polling an export never spends your data quota. |

The window is sliding: a request made 24 hours ago frees its slot.

## Quota in response headers

Rate-limit state comes back as HTTP headers on every response (not in the
body):

| Header                  | Meaning                                                             |
| ----------------------- | ------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Requests allowed in the current window.                             |
| `X-RateLimit-Remaining` | Requests left before you're throttled.                              |
| `X-RateLimit-Reset`     | ISO timestamp when the window resets.                               |
| `X-Request-Id`          | Unique id for the request (`req_…`); include it in support reports. |

## When you exceed the limit

Over-quota requests return `429` with a `rate_limit_error` envelope and a
`Retry-After` header (seconds):

```json theme={"dark"}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 42 seconds."
  }
}
```

```
Retry-After: 42
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-08-22T09:14:33.000Z
```

Back off until `Retry-After` elapses (or `X-RateLimit-Reset`), then retry.
Over MCP, the tool call returns an error message instead of a result.

<Note>
  The limiter **fails open**: if the rate-limit backend is briefly
  unavailable, requests are allowed through and no `X-RateLimit-*` headers are
  emitted. Don't depend on the headers always being present.
</Note>

## Staying well under the limit

* Use `page_size=100` when paging; fewer, larger pages cost fewer requests.
* For a complete copy of the data, one [export](/legal/exports) replaces
  hundreds of list calls.
* For aggregates, call [`GET /v1/analytics`](/legal/api-reference/get-analytics)
  once rather than paging rows to count them.
* Sync incrementally with `since` on the actuaciones feed (see
  [Pagination & filters](/legal/pagination)) instead of re-reading the portfolio.

<Card title="Next: Errors" icon="triangle-exclamation" href="/legal/errors">
  The error envelope and every error code.
</Card>