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 tied to a paid tier — tight at the floor, generous at the top, $200 per month minimum to leave Free.
TwitterAPI.io imposes a per-account QPS ceiling, published at /qps-limits and raisable on request — no price-tier gate. What follows is the spec sheet and the patterns that keep workloads inside it.
Official tier envelope
Verify pricing at developer.x.com 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. Default ceiling is provisioned at account creation; the live rate sheet is at /qps-limits.
Two operational facts shape design around it:
- ⇒No price-tier gate. Raising the ceiling is a free support request — there is no Pro / Enterprise upsell prerequisite.
- ⇒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 · Submit ticket with target QPS + workload sketch
- 03 · New ceiling provisioned typically same business day
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 with a Retry-After header indicating when you can resume. Respect it — 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. If you need higher concurrent throughput on TwitterAPI.io, request the QPS ceiling raised on your account rather than spreading the workload across multiple keys.
How do I work around the official free tier's ~1,500 posts/month cap?
Either upgrade to Basic ($200/month, larger cap), or move to a third-party API for the workload that doesn't strictly need first-party origin. 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 paid official tiers.
What is the QPS limit on TwitterAPI.io?
Default is set per account at signup. The current published rate sheet lives at /qps-limits. Raising the ceiling is a free support request — there is no price-tier gate behind higher QPS.
How do I detect rate limiting in code?
Check the HTTP status code on every response. On 429, read the Retry-After header (in seconds) and back off accordingly. For long-running scrapers, also watch the rate-limit-remaining header and pre-emptively pace requests as the counter approaches zero, rather than waiting for the 429.
Linked specifications
Default QPS clears most workloads.
Higher ceiling, free support ticket.