# Rate limits

Requests per minute per key and per organization, and the headers that report them.



Each key has a budget of requests per minute, and so does its organization across all its keys. The
budget refills continuously.

These numbers are provisional while the API is new, and may change. The `RateLimit-Policy` header on every response always states the budget that applies to
your key, so read it rather than hard-coding the table.

| Plan       | Per key, per minute | Per organization, per minute |
| ---------- | ------------------- | ---------------------------- |
| Trial      | 60                  | 60                           |
| Solo       | 120                 | 240                          |
| Starter    | 300                 | 600                          |
| Growth     | 600                 | 1,200                        |
| Scale      | 1,200               | 3,000                        |
| Enterprise | 2,400               | 6,000                        |

During the trial, keys can only read and an organization can hold one key.

## Costly requests [#costly-requests]

A few requests also spend from a smaller budget of their own, because each one starts real work.
These are provisional too.

| Plan       | Sessions created per minute (organization) | Cloud Computer operations per 10 minutes (AI team) | Invitations per day (organization) | Open event streams (organization) |
| ---------- | ------------------------------------------ | -------------------------------------------------- | ---------------------------------- | --------------------------------- |
| Trial      | 0                                          | 0                                                  | 0                                  | 2                                 |
| Solo       | 5                                          | 6                                                  | 10                                 | 5                                 |
| Starter    | 10                                         | 6                                                  | 20                                 | 10                                |
| Growth     | 20                                         | 6                                                  | 50                                 | 20                                |
| Scale      | 40                                         | 12                                                 | 100                                | 50                                |
| Enterprise | 80                                         | 24                                                 | 200                                | 100                               |

Over one of these, the answer is `429 rate_limited` with `limit_scope` naming the budget
(`session_create`, `computer_op` or `invite`) and `retry_after`. Too many open streams is
`429 too_many_streams`. A session also takes at most 4 streams at once.

## Headers [#headers]

Every response reports the key's budget:

```
RateLimit-Policy: "credential";q=300;w=60, "org";q=600;w=60
RateLimit: "credential";r=297;t=1
```

`q` is the budget, `w` the window in seconds, `r` what is left and `t` the seconds until the budget
is full again.

## Over the limit [#over-the-limit]

An [agency key](/docs/api/agency-keys/) has its own budgets: 600 requests a minute per key on each
API server (the cap is per server, so the total across servers can be higher), and a separate budget
for your agency in each client, the size of that client's organization budget. Agency traffic never
spends the client's own budget. Over the client budget, `limit_scope` is `agency_client`.

The answer is `429 rate_limited` with `limit_scope` (`credential`, `org` or `agency_client`), `retry_after` and a
`Retry-After` header. Wait that long, then retry. Back off further if it happens again.

An address that keeps sending invalid keys is refused for a while before its keys are even checked:
`429 rate_limited` with `limit_scope: "ip"`. During that wait a valid key from the same address is
refused too, so fix the bad key first.

Our edge also limits requests per IP address. Those refusals can arrive without a problem document,
so treat every `429` as "wait and retry".
