Developers

On this page
Using the API

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, 403 or 404 Problem 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/meta is 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 exactly Retry-After seconds later can be refused again, with Retry-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, 0 on a 429.
  • 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.

Important

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 newerThan instead 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, wait Retry-After seconds, 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.