How do you get an entire Twitter thread with an API?

Any id in the chain is enough

The id parameter accepts any tweet in the thread, not only the first one. That matters more than it sounds, because in practice the id you hold is rarely the root: it arrived from a search hit, a mentions feed, or somebody quoting the middle of a chain at you. Passing that id returns the ordered list for the whole chain anyway, with no walk backwards to find a starting point and no guess about which post is the opener. The only other parameter is cursor, and it is documented as existing for very long threads rather than as something a normal call needs. So the ordinary request is one required id and nothing else.

What comes back

The response has three fields. thread is an array of tweet objects in reading order, each carrying its own id, text, created_at and author. count is how many entries landed on this page. next_cursor is the paging token. Because the array is already ordered, rendering a thread is an iteration and nothing more: no sorting by timestamp, no reassembling parent and child links, no deciding which of several replies continues the chain. The tweet objects are the same shape the rest of the surface returns, so a component that renders a search result renders a thread entry unchanged. Numeric ids come back as strings throughout, deliberately, because a tweet id overflows a JavaScript number.

Paging a very long thread

Cursor handling here follows the shared contract used across the surface, and that contract has one edge worth reading carefully. next_cursor comes back null on the final page for list style endpoints, but follower graph endpoints return a non null cursor even on their last page, so the instruction that holds everywhere is to stop paging when the collection array itself comes back empty rather than trusting the cursor to turn null. Applied to a thread that means: if next_cursor holds a string, send it back as cursor to collect the rest of the chain, and stop when thread returns nothing. Since the parameter is documented as being for very long threads, treat a second page as the exception rather than a loop you always run.

What it does not return

This returns the author's own connected thread, which is the chain that one account wrote, not the conversation around it. Replies from other people are a different question with a different route: tweet/replies pages the direct replies to a given post, taking an id and a cursor, and it is billed at the ordinary read rate rather than the premium one. Keeping the two apart is what lets the thread call stay a single request. The selection of which posts belong to the author's narrative and which are bystanders happens upstream, which is precisely the work this endpoint exists to absorb on your behalf, and it is the part that is genuinely awkward to reimplement.

The single tweet companion

tweet/detail is the cheap companion and usually the first call. It resolves one id into the complete tweet object: author, favorite_count, retweet_count, reply_count and view_count, plus attached media and any quoted tweet. That is where you check whether an opening post is worth expanding at all, since engagement on the first tweet is a reasonable proxy for whether the chain matters to you. The division of labour is simple enough to state in one line. Use tweet/detail when you have one id and want everything about that single post, and reach for tweet/thread only when you actually want every post in the sequence rather than the one you happened to be handed.

Why the price tier is different

The cost table marks tweet/thread as premium for full thread expansion and prices it at $0.004. The reasoning is stated on the route priced beside it, grok/chat, which sits at the same tier: the premium is attributed to the wall clock cost of holding a long connection open plus the upstream work behind it, rather than to metering per record returned. That framing is useful because it tells you what you are actually paying for. You are not being charged by the tweet. You are paying for a request whose duration is not proportional to anything you control, and whose length you could not have predicted before you made it.

The arithmetic against doing it by hand

Work the numbers before building the manual version. One expansion is $0.004, so five threads cost the same as twenty five ordinary reads, and expanding a hundred threads comes to forty cents. Against that, stitching a chain yourself is an unbounded number of standard calls at $0.0008 each, and the count is not knowable up front because thread length is not knowable up front. The comparison flips the other way for engagement figures: if you want favorite and view counts per post, a twelve post thread means twelve detail lookups at just under a cent in total, which is more than double what the expansion itself cost you. For scale, the $0.50 of credit a new account starts with is 125 expansions, or 625 ordinary reads if you spend it the other way.

Rate ceiling and batching

One ceiling covers every route on a key: 600 requests a minute and 20 concurrent. Because expansions are the expensive call here, that ceiling is rarely what limits a thread job, spend is. Six hundred expansions inside a minute is $2.40, so a queue saturating the rate limit with this endpoint is burning money faster than most crawls justify. Run it at whatever concurrency your pipeline wants up to twenty, and if you do reach the ceiling the response is a 429 carrying a Retry-After header, which tells you how long to wait rather than leaving you to model a separate quota for every endpoint you touch. The ceiling is flat across routes and applies per key, so a cheap search loop and an expensive expansion loop draw on the same allowance instead of each getting one of their own.

Where the ids come from

Thread ids come from wherever you already read posts. A keyword search returns tweet ids, a mentions feed returns tweet ids, and a reply or a quote carries one too, so any of those pipelines can hand an id straight to this route with no resolution step in between. The practical pattern is a two stage job: find candidate posts cheaply with search or a timeline read at the standard rate, filter them on engagement with tweet/detail, then expand only the ones that survived the filter. That keeps the premium call rare, which is the only real budget control this endpoint gives you. A detail lookup is a fifth of an expansion, so discarding four candidates in five already pays for the filter. $0.004 a call, per the rates we publish.

One thread call against stitching it by hand

Questions and answers

Do I need the first tweet of the thread?

No, any id inside the chain works. Pass the one you happen to have, whether it came from a search hit, a mention or somebody quoting the middle of it, and the route resolves the connected set for you. That is the point of the endpoint: there is no walking backwards to find a root, and no guessing which of the posts you can see is the opener.

Does it include other people's replies?

No. It returns the author's connected thread, so what comes back is the chain that one account wrote rather than the discussion around it. For the answers other accounts left, tweet/replies pages the direct replies to a given post and is billed at the ordinary read rate rather than the premium one. The two routes answer genuinely different questions and are priced accordingly.

How do very long threads paginate?

The response carries next_cursor alongside count. If it holds a string, send it back as cursor to collect the rest. The safest stop condition across this API is an empty collection array rather than a null cursor, since some endpoint families return a cursor even on the last page. The parameter is documented as being for very long threads, so a second page is the exception.

Why does a thread cost more than a tweet lookup?

It sits in a premium tier at $0.004 against $0.0008 for a normal read. The cost table calls it full thread expansion, and on the route priced beside it attributes that tier to the wall clock cost of holding a long connection open plus the upstream work behind it, rather than to how many records land in the array you get back.

Can I get engagement numbers for each post in the thread?

The thread array holds tweet objects, and tweet/detail is the route documented with favorite_count, retweet_count, reply_count and view_count on a single id. If you need those figures pinned down per post, take the ids from the thread and look each one up, which is a standard read apiece. On a twelve post chain that costs more than the expansion did.

Should I call tweet/detail or tweet/thread?

Call tweet/detail when you have one id and want everything about that post, including its engagement counts, attached media and any quoted tweet. Call tweet/thread when you want every post in the author's chain in reading order. The cheap pattern is both in sequence: detail first as a filter, expansion only on the posts that clear whatever bar you set.

Are the tweet ids safe to store as numbers?

No. Ids are returned as strings throughout this API precisely because a tweet id is large enough to lose precision in a JavaScript number. Keep them as strings from the response all the way into storage. Converting one to a number and back is the classic way to end up requesting a tweet that is close to the one you meant but is not it.

Can I combine thread expansion with search?

Yes. A search hit gives you a tweet id, and that id is all the thread route needs, so a pipeline that finds posts by keyword can expand each interesting one into its full chain. Budget for it, because the expansion sits in a higher tier than the search that found the post, which makes filtering before expanding the whole game.

How many thread calls can I make per minute?

One flat ceiling covers every route on a key: 600 requests a minute with 20 concurrent. For this endpoint the practical limit is money rather than throughput, since 600 expansions in a minute is $2.40. If you do hit the ceiling, the response is a 429 carrying a Retry-After header telling you how long to hold off, rather than a per endpoint quota you have to model. The allowance is shared across every route on the key, so a search loop running beside your expansions draws on the same 600.

How do I know when a thread is finished?

Read count and next_cursor together. A null or empty next_cursor on a page that returned tweets is the end of the chain. The reliable rule across this API is to stop when the collection array comes back empty, because a couple of endpoint families keep returning a cursor even after the last row, and a loop trusting only the cursor will spin.

Keep reading

• Twitter REST API
• Twitter Engagement API
• Cost calculator
• How do you get tweets programmatically?
• Full API reference
• Publishing long-form as an X Article