Rate limits
Reads come out of a budget that belongs to your key's account and is counted over a window of 15 minutes. The budget's size depends on the account's subscription level; the window doesn't change. Getting a token has a separate, smaller limit.
Reads per subscription level
Level 0 is the entry plan; an account without a subscription gets the same budget.
| Subscription | Reads per 15 minutes |
|---|---|
| None or level 0 | 25 |
| Level 1 | 40 |
| Level 2 | 55 |
| Level 3 | 80 |
| Level 4 | 150 |
| Level 5 | 660 |
- One budget for all reads. Every v2 read your account makes counts against the same budget, whichever endpoint it calls. A read is one request, however many items it returns, and a read that fails with a
400,403or404Problem Details response still counts. A missing or expired token is refused before it's counted. - It belongs to the account, not the token. A new token doesn't reset it, and neither do new keys.
- A Site's key uses the Site's own subscription level, not its owner's. A Site doesn't need a subscription, so a Site that has none is in the first row.
/v2/metais free: it isn't limited and doesn't count.- Version 1 reads have their own limits. Version 1 reads don't spend version 2's budget, and version 2 reads don't spend version 1's. Getting a token is the exception: both versions share one token limit.
The window
The budget is counted over a fixed window of 15 minutes that starts with your first read. When it ends, the next read starts a new window with a full budget. Windows aren't tied to the clock, so they don't start on the hour or the quarter hour.
Once the budget is spent, every read gets a 429 Too Many Requests until the window ends. A refused read doesn't count, and trying early doesn't move the end of the window.
When you get a 429
The response says how long to wait:
Retry-After: seconds until the window's last second. Wait one second more: the window's last second still belongs to it, so a call made exactlyRetry-Afterseconds later can be refused again, withRetry-After: 0.X-RateLimit-Limit: the limit that refused you. On a read, that's your read budget, unless your token is stale (below): then it's the much smaller per-IP limit of 3 requests per 15 minutes.X-RateLimit-Remaining: reads left in the window,0on a429.X-RateLimit-Reset: the window's last second, as a Unix time in seconds. Reads work again from the second after it.
These headers come only with a 429. Successful reads don't say how much budget is left, so if you need to know, count your own reads.
A 429 straight after a run of 401s usually means your token is stale, not that your budget is spent: Errors explains why. Get a new token rather than waiting.
Getting a token
The token call has its own limit: 3 requests per 5 minutes for each account. /v2/auth/token and version 1's /auth/token share it, and failed requests count too. A token lasts a little over eight hours, so get one, keep it, and reuse it: Authentication shows how.
Staying within the limits
- Reuse your token until it expires, rather than getting one for each call.
- Keep what you've read. Profiles, hubs and catalogs change rarely; read them again now and then, not on every page view.
- Poll new transmissions with
newerThaninstead of re-reading whole pages: Polling for new transmissions shows how, and how a minute's interval fits the level 0 budget. - Use the largest page you need. One read of 25 transmissions costs the same as one read of 5.
- On a
429, waitRetry-Afterseconds, plus one, then carry on. Don't retry in a loop.
Moving from version 1
Version 1 had a separate budget for each of its three reads: transmissions, hashtags and events. Version 2 has one budget, the size of all three put together, for every read. So an app moving over has at least as many requests as before, at every level.
Page sizes changed, though, and the budget counts requests, not items:
- Hashtag feed: version 1 returned up to 100 transmissions a call; version 2 returns up to 25. Reading 100 now takes 4 reads.
- Account feed: up from 20 to 25 a call.
- Events: still up to 100 a call.
Moving from v1 covers the other changes.