Twitter Unofficial API Guide

The measurements behind this page

Everything above is a summary of work written up in longer form. If you are deciding between routes rather than reading about them, these are the pieces that carry the numbers and the code.

Data you can retrieve via Twitter scraping

Anything a logged-out or logged-in browser can see on x.com is, in principle, retrievable. In practice the useful surface groups into six families, and knowing which family a field belongs to tells you how stable it is.

What is not retrievable at any price: protected accounts you do not follow, deleted posts, draft posts, and analytics X only shows an account owner. A vendor offering any of those is describing something other than public data. We publish 109 endpoints across the six families above, and the boundary between them and the list in this paragraph is the same boundary X draws.

Scrape Twitter user tweets and profiles data in real time

Real time on X means one of two shapes, and they have different costs and different failure modes. Choosing the wrong one is the most common design mistake on this kind of integration.

Incremental polling is a loop that asks for anything newer than the last thing it saw. Store the highest tweet id and pass it as since_id, and each cycle returns only what arrived since, so a quiet minute costs one call and returns an empty array. At $0.0008 a call, a one-minute cycle on one account is about $34.56 a month, and a five-minute cycle is about $6.91. Freshness is bounded by the interval, which is the honest limitation: a one-minute poll can be up to a minute behind, and no amount of engineering changes that.

Push delivery flips the direction. A monitor watches one handle and posts new activity to a webhook you own, optionally narrowed to posts linking to a given domain or with replies turned off. You get a signed delivery instead of a schedule, and you can fire a test delivery before you depend on it. Profiles do not push, because a bio edit raises no event, so profile freshness is always a re-read on whatever cadence your product needs.

The practical pattern for most products is both: push for the handles you must not miss, polling for the search queries and the wider watchlist, and a nightly re-read for profile fields. Whatever you choose, one flat ceiling applies, 600 requests a minute, so throughput is a capacity question rather than a plan question.

Why a 200 response is not proof the data is complete

This is the failure mode that separates a scraping-backed API from an official one, and almost nobody tests for it. An official API that cannot serve you returns an error. A scraping layer that gets a partial page from upstream can return a perfectly valid 200 with fewer rows than exist, and every monitor you have will report green.

It matters most on the surfaces where you cannot eyeball the answer: follower pagination that stops early, a search that returns the first two pages of a ten-page result, a timeline missing the replies. The bug is invisible in your logs because nothing failed. You find it weeks later when a count in a report is wrong.

Three checks are worth writing once and keeping. Assert that a paginated walk either exhausts the cursor or hits a limit you set deliberately, and alert on any other exit. Pick two or three accounts whose real numbers you can verify by hand and reconcile against them on a schedule. And when you evaluate any vendor in this category, including us, run the same query on two of them and diff the row counts rather than comparing response times. Latency is easy to measure and rarely the thing that hurts you.

Every endpoint carries its price inside the OpenAPI document

Most of this category publishes a pricing page and a spec, and lets you join them by hand. We put the cost on the endpoint itself. Each of the 109 published paths carries an x-cost-usd field in the OpenAPI document, so a client can read what a request will cost before it sends it.

Two things follow from that, and both are the reason we do it. A repricing becomes a visible diff in a file you can pin, rather than a quiet edit on a marketing page. And an agent choosing between two calls at run time can see the cost of each without a human having read the rate card, which is the difference between a budget you enforce in code and a budget you hope about. Per our own spec, 62 of those paths bill the standard read rate, 24 are free, and the remainder sit between $0.0016 and $0.01.

A pre-ship checklist for an unofficial integration

Whichever route you take, self-hosted library or hosted API, these are the six things that decide whether the integration is still working in six months.

• Persist your pagination anchor outside the process. A restart that loses the anchor re-reads a page you already billed and processed.
• Put the response mapping in one adapter. Field names differ between every provider in this category. One module means a future move is a one-file change.
• Retry only 429 and 5xx, with backoff. A 4xx is a bug in your request. Retrying it five times turns a fast failure into a slow one and bills you for both.
• Cap the page walk explicitly. An unbounded loop against a large follower graph is how a $2 job becomes a $200 one overnight.
• Alert on empty, not just on error. A collector returning zero rows for six hours is usually broken, and it is the one state a health check based on status codes cannot see.
• Write down what you are allowed to store. Public data is not the same as unrestricted data. Decide your retention and redistribution position before you have a database full of it, not after.

Frequently Asked Questions