
Rate-limit envelope
& safe operating zone
Two independent rate ceilings shape any build on the X (Twitter) ecosystem. The official X Developer Platform imposes per-endpoint caps on top of pay-per-use billing — $0.005 per post read, $0.010 per user read, no subscription, and post reads capped at 3 million per monthly billing cycle before Enterprise takes over.
TwitterAPI.io imposes a per-account QPS ceiling, published at /qps-limits: 0.2 requests per second for accounts that never paid, 20 once paid, and up to 1,000 on the top subscription tiers. What follows is the spec sheet and the patterns that keep workloads inside it.
Official access envelope
Verify pricing at docs.x.com/x-api/getting-started/pricing before purchase. Load profile is a coarse visualization, not a published number.
Third-party envelope (TwitterAPI.io)
TwitterAPI.io rate-limits per API key, measured in queries per second. The ceiling follows the account's tier: 0.2 requests per second for accounts that never paid, 20 once paid, 50 on Scale and 500 on Business; the live rate sheet is at /qps-limits.
Two operational facts shape design around it:
- ⇒Published per tier. The first payment lifts an account from 0.2 to 20 requests per second; the Scale and Business tiers raise it to 50 and 500.
- ⇒Per-key, not per-IP. Spreading workload across many keys to dodge the limit usually creates more problems than it solves; one key with the right ceiling is the cleaner answer.
- 01 · Establish nominal throughput for one week
- 02 · Compare the peak with the tiers at /qps-limits
- 03 · Move to the tier whose ceiling covers it
Procedures for staying inside the envelope
Request the maximum page size
Two hundred followers per call is sixty-seven percent cheaper per follower than twenty per call, after the bulk-tier discount applies. The same principle holds for search (twenty results per call) and any other paginated endpoint.
Use IDs-only endpoints for graph diffs
/twitter/user/followers_ids returns five thousand numeric IDs per call for roughly two cents — about fifty percent cheaper than the profile-included variant. Hydrate selected IDs through /twitter/user/info only when profile data is needed downstream.
Pace pre-emptively, not reactively
Read the rate-limit-remaining header (or equivalent) and slow request issuance as it approaches zero. A reactive back-off after a 429 wastes the seconds until the next reset window; a proactive pace stays inside the envelope.
Cache for the lifetime of the data
Tweet content is immutable; only its engagement metrics drift. User profiles change slowly. Hourly polling for a profile that updates once a week is ninety-six percent waste — a daily cache eliminates almost all of it.
Stream when the goal is freshness
Polling search every thirty seconds to detect new tweets is the wrong tool. The WebSocket stream pushes new matches as they appear — fewer calls, lower latency, no rate-limit pressure.
Notes
What happens when I hit a rate limit?
Both official and third-party APIs return HTTP 429. The official X API tells you when the window resets in its x-rate-limit-reset header; TwitterAPI.io sends no Retry-After or rate-limit header, so wait about a second and retry with backoff. Either way, repeated calls after a 429 do not reset the counter and may surface as account-level throttling on the official side.
Are rate limits per IP, per key, or per project?
Official X v2 limits are scoped per project + per endpoint family. TwitterAPI.io limits are per API key. The TwitterAPI.io ceiling follows the account's tier (published at /qps-limits), so if you need higher concurrent throughput, move to a higher tier rather than spreading the workload across multiple keys.
How do I work around the official API's 3 million post-read monthly cap?
Official pay-per-use billing ($0.005 per post read) stops at 3 million post reads per monthly billing cycle; above that X requires Enterprise through an interest form, with no public price. The other route is moving the workload that doesn't strictly need first-party origin to a third-party API. Most evaluation, prototyping, and analytics workloads can live entirely on third-party access — write actions and certain official-only endpoints are the workloads that justify staying on the official API.
What is the QPS limit on TwitterAPI.io?
It depends on the account's tier: 0.2 requests per second for accounts that have never paid, 20 once the account has paid, 50 on Scale and 500 on Business, and up to 1,000 requests per second (the highest limit applies to the top subscription tiers). The current published rate sheet lives at /qps-limits.
How do I detect rate limiting in code?
Check the HTTP status code on every response. On 429, back off and retry: on the official X API wait until the time in x-rate-limit-reset, and watch x-rate-limit-remaining to slow down before you hit zero; TwitterAPI.io sends no rate-limit headers, so pace requests to your per-second limit and retry a 429 after about a second with exponential backoff.
Linked specifications
20 requests per second once paid.
Higher ceilings by tier, up to 1,000.