---
title: "Rate limits"
description: "600 requests a minute per workspace, the headers that tell you where you stand, and what to do with a 429."
canonical: https://docs.mentio.dev/rate-limits
markdown: https://docs.mentio.dev/rate-limits.mdx
---

# Rate limits

600 requests a minute per workspace, the headers that tell you where you stand, and what to do with a 429.

A workspace may make 600 requests a minute. Read this to stay under the limit and to handle a `429` when you hit it.

## The limit [#the-limit]

* 600 requests a minute, counted across every API key and OAuth token the workspace holds.
* The window slides: a request stops counting sixty seconds after it was made.
* MCP tool calls count in the same window.
* The dashboard's own traffic does not count, so a script at its limit never locks you out of the app.

The limit is per workspace, not per key. Two scripts on two keys of the same workspace share the 600.

## Read the headers [#read-the-headers]

Every counted response carries three headers:

| Header                  | Meaning                                |
| ----------------------- | -------------------------------------- |
| `X-RateLimit-Limit`     | Requests admitted per minute (600).    |
| `X-RateLimit-Remaining` | Requests left in the current window.   |
| `X-RateLimit-Reset`     | Unix seconds when the next slot frees. |

## Handling a 429 [#handling-a-429]

Past the limit, a request answers `429` with the `rate_limited` code. It carries a `Retry-After` header (seconds) and `retryAfterSeconds` in the body.

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this workspace; retry in 12 s",
    "retryAfterSeconds": 12,
    "requestId": "3f9c1e2a-7b4d-4c1e-9a0b-2d5e6f7a8b9c"
  }
}
```

Wait that many seconds, then send the same request again.

The SDKs and the CLI do not retry on their own. They return the 429 like any other error, so the wait is yours to write.

Spreading a large job over time beats retrying. 600 a minute is ten a second, enough to page through every mention of a busy workspace without touching the limit.

## Endpoints with their own cap [#endpoints-with-their-own-cap]

A few endpoints keep a tighter cap on top of the workspace limit:

| Endpoint                                        | Cap               |
| ----------------------------------------------- | ----------------- |
| CSV export of mentions                          | 6 a minute        |
| CSV export of people                            | 6 a minute        |
| Keyword health (`GET /v1/keywords/{id}/health`) | 30 reads a minute |
| Keyword health with `ai=true` (language model)  | 20 calls an hour  |
| [Usage breakdown](/billing#cost-per-keyword)    | 30 reads a minute |

The keyword health caps count every caller, the dashboard included. The usage breakdown cap does not count the dashboard.

The exports are capped because each scans up to ten thousand rows.

## Related [#related]

* [Errors](/errors): every error code, `rate_limited` included
* [Conventions](/conventions): the rules every endpoint follows
* [Exports](/guides/exports): download mentions and people as CSV
* [Keyword health](/guides/keyword-health): the health report and its AI read