# API rate limits

> How many requests a Ranqo API key can make each minute on each plan, the headers that report it, and how to handle a rate-limited request.

Source: https://ranqo.ai/docs/api/rate-limits

Each key can make a set number of requests a minute, depending on the account's plan. The limit belongs to the key, not the account, so two tools with their own keys do not use each other's allowance.

| Plan | Requests per minute | Active keys |
| --- | --- | --- |
| Starter | Not included | Not included |
| Pro | 60 | 5 |
| Agency Growth | 120 | 10 |
| Agency Scale | 300 | 25 |

## Reading the limit from a response

Every response to a request the key's limit admitted, an error included, reports the key's limit and what is left of it, in the IETF `RateLimit` header fields:

```http
RateLimit-Policy: "minute";q=60;w=60
RateLimit: "minute";r=42;t=17
```

- In `RateLimit-Policy`, `q` is the key's limit and `w` the window in seconds.
- In `RateLimit`, `r` is the requests left in this window and `t` the seconds until it resets.

A refusal that comes before the key's limit is counted carries no `RateLimit` fields, such as a key or plan refusal (a `401` or `403`), `api_key_in_url`, a `429` for too many failed attempts or a `503`. A `429` from the key's own limit carries them.

`GET /v1/account` returns the same limit as `rate_limit.requests_per_minute`.

## At the limit

A request over the limit is refused with `429` and the code `rate_limited`. The `Retry-After` header, and `retry_after_seconds` in the body, say how many seconds to wait. Wait that long, then retry; retrying sooner is refused again.

If the service that counts requests is briefly unavailable, the API refuses the request with `503` and `service_unavailable` rather than serve it uncounted. Its `Retry-After` is 5 seconds.

## Using fewer requests

- A brand is tracked every 7 days, so the numbers change at most once a run. Reading the reports once a day is plenty for a dashboard.
- Reports are kept for 10 minutes for the same window and filters, so asking again within that time returns the same figures, unless a run completes in between.
- Read lists with the largest `limit` your tool can handle (see [Pagination](https://ranqo.ai/docs/api/pagination)).
- Retry a `429` or `503` after the `Retry-After` delay, and back off further if it repeats.