Skip to main content
GET
Tweet thread API, conversation export & authors
Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page or ID list, Xquik returns fewer results. If zero paid results are affordable, it returns 402 insufficient_credits.
1 credit per tweet returned · All plans from $0.00012/credit · Supports guest paid reads
Get tweet thread returns tweet rows in the conversation thread around one source tweet. It is also useful as a tweet thread API, X thread API, Twitter thread API, conversation thread API, or thread context endpoint. The canonical endpoint remains GET /api/v1/x/tweets/{id}/thread.
The Node.js and Python snippets write JSON Lines thread rows plus a separate checkpoint instead of raw response pages. Persist each mapped row and the latest next_cursor so a support timeline, research job, moderation queue, or agent handoff can resume from the last completed page without duplicate rows.

Direct tweet thread handoff

Use GET /api/v1/x/tweets/{id}/thread when a workflow needs ordered thread context as durable rows around one tweet. Store source_tweet_id, thread_tweet_id, text, author_id, author_username, author_name, author_followers, author_verified, author_profile_picture, created_at, conversation_id, in_reply_to_id, media URLs, and a separate next_cursor checkpoint for downstream jobs.

Thread rows

Store tweets[] as the thread context rows returned for one source tweet.

Stable upserts

Store tweets[].id as thread_tweet_id with source_tweet_id for idempotent imports.

Reply joins

Store conversationId, inReplyToId, inReplyToUserId, and inReplyToUsername to rebuild thread structure.

Author joins

Store tweets[].author.id, username, name, followers, verified, and profilePicture for review, CRM, or research tools.

Media context

Store media[].mediaUrl, entities, quoted_tweet, and retweeted_tweet when returned to preserve attached context.

Next page

Store has_next_page and next_cursor; pass next_cursor back as cursor only when has_next_page is true.

Credit-limited pages

Use tweets.length, not a requested page size, for row counts. Low balances can return fewer rows.

Saved exports

Use thread_extractor when you need a saved extraction job or CSV, JSON, or XLSX export.
Direct tweet thread reads cost 1 credit per tweet returned. Low credit balances can return fewer tweets than a full page; zero affordable results return 402 insufficient_credits.

Reconstruct an ordered tweet thread

Use this route when several connected posts form one authored sequence. Start from a known tweet ID. Store each tweet ID, text, author, creation time, engagement counts, media, and thread position. Keep the starting tweet ID with the complete result. Render posts in the returned thread order. Do not sort by engagement counts. Preserve media and quote relationships inside each post. Thread results can support long-form reading, approved archiving, or conversation context. A reply from another author may belong to a different conversation path. Use tweet replies for responses under one post. Use quote tweets for external commentary. Use exact tweet lookup when only one post is required.

Path parameters

string
required
Tweet ID (numeric string).

Query parameters

string
Pagination cursor from next_cursor in a previous response. Omit for the first page. Pass a cursor only when has_next_page is true.
integer
Tweets per page. Range: 1-100. Defaults to 20.

Tweet result filters

string
Filter to posts from this username. The @ prefix is optional.
string
Filter to replies directed to this username.
string
Filter to posts that mention this username.
string
Only include posts with this language code.
string
Include posts created on or after this date or timestamp.
string
Include posts before this date or timestamp.
string
Use images, videos, gifs, media, links, or none.
integer
Require this minimum like count.
integer
Require this minimum repost count.
integer
Require this minimum reply count.
integer
Require this minimum quote count.
integer
Require this minimum view count.
integer
Require this minimum bookmark count.
integer
Allow this maximum like count. Missing counts pass.
integer
Allow this maximum repost count. Missing counts pass.
integer
Allow this maximum reply count. Missing counts pass.
integer
Allow this maximum quote count. Missing counts pass.
boolean
When true, only return posts from Blue-verified authors.
boolean
When true, only return posts from verified authors.
string
Use include, exclude, or only for replies.
string
Use include, exclude, or only for reposts.
string
Require this exact phrase.
string
Exclude comma-separated or whitespace-separated terms.
string
Require at least 1 comma-separated or whitespace-separated term.
string
Match these hashtags. Separate values with commas or spaces.
string
Match these cashtags. Separate values with commas or spaces.
string
Use include, exclude, or only for quote posts.
string
URL substring or domain that must appear in tweet URL entities.
string
Filter to tweets in this conversation thread.
string
Only include replies to this tweet ID.
string
Filter to quote tweets of this tweet ID.
string
Filter to retweets of this tweet ID.

Which thread endpoint?

Tweet thread

Use GET /x/tweets/{id}/thread for conversation thread context around one tweet.

Tweet replies

Use GET /x/tweets/{id}/replies when you need reply tweet rows under one source tweet.

Quote tweets

Use GET /x/tweets/{id}/quotes for tweet rows that quote one source tweet.

Search tweets

Use GET /x/tweets/search when you need keyword, operator, or structured-filter discovery across many tweets.

Saved exports

Use Create extraction with toolType=thread_extractor when you need a saved job or CSV, JSON, or XLSX export.

Single tweet

Use Get tweet when you only need one tweet object by ID.

Headers

string
Full account key. Sessions and OAuth also work.
string
Bearer xq_your_guest_key_here for paid_reads.

Response

200 OK

object[]
Array of tweets in the thread, ordered chronologically. Tweet object fields.
string
Tweet ID.
string
Tweet text.
string
Tweet type. Omitted if unavailable.
string
ISO 8601 creation timestamp.
boolean
Whether this is a Note Tweet. Omitted if unavailable.
number
Like count. Omitted if unavailable.
number
Retweet count. Omitted if unavailable.
number
Reply count. Omitted if unavailable.
number
Quote tweet count. Omitted if unavailable.
number
View count. Omitted if unavailable.
number
Bookmark count. Omitted if unavailable.
string
Permalink URL on X. Omitted if unavailable.
string
Tweet language code. Omitted if unavailable.
boolean
Whether this tweet is a reply in the thread.
string
Tweet ID being replied to. Omitted if not a reply.
string
User ID being replied to. Omitted if unavailable.
string
Username being replied to. Omitted if unavailable.
string
Thread conversation ID.
string
Client used to post the tweet. Omitted if unavailable.
number[]
Start and end offsets for rendered tweet text. Omitted if unavailable.
boolean
Whether replies are limited. Omitted if unavailable.
boolean
Whether this tweet quotes another tweet. Omitted if unavailable.
object
Parsed entities. Omitted if unavailable.
object
Disclosure metadata for paid partnership and AI-generated media labels. Includes advertising.isPaidPromotion and aiGenerated.hasAiGeneratedMedia when X returns them. Omitted if unavailable.
object
Tweet author profile. Omitted if unavailable. Author object fields.
string
Author user ID.
string
Author handle without @.
string
Author display name. Omitted if unavailable.
number
Follower count. Omitted if unavailable.
boolean
Whether the author is verified. Omitted if unavailable.
string
Author profile image URL. Omitted if unavailable.
object[]
Media attachments. Omitted when the tweet has no media. Media object fields.
string
Direct media URL.
object[]
Available video renditions with bitrate, content type, and URL. Omitted for images.
string
Media type.
string
Shortened URL from the tweet text.
object
Embedded quoted tweet. Omitted if not a quote tweet.
object
Original retweeted tweet. Omitted if not a retweet.
boolean
Whether more results are available.
string
Cursor for the next page.

400 Invalid tweet ID

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.

402 Payment required

Account keys get account options; guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

502 X API unavailable

The read service returned an error. Retry after a short delay.

429 Rate limit exceeded

Your tier rate limit was exceeded. Wait for the Retry-After header before retrying.

424 Dependency failed

The normalized v1 response contract can return 424 when the read service is unavailable.