Skip to main content
GET
Twitter list tweets API & timeline export guide
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 automatic for maximum coverage or standard for legacy pagination.
string
Use include, exclude, or only for native repost records.
Use this Twitter Lists API to retrieve Twitter List tweets from one curated timeline. Export Tweet text, authors, replies, reposts, likes, quotes, media, and cursor pages. Provide the numeric List ID from its X URL.

Twitter list tweets questions

What does the Twitter lists API return?

The endpoint returns posts from accounts in one X List timeline. Each page can include Tweet text, author profiles, timestamps, engagement counts, media, and pagination fields. The response represents one observed timeline window. It does not prove a complete archive or permanent List membership.

How do I export tweets from a Twitter list?

Request the first page with the numeric List ID. Normalize each Tweet into one row. Store has_next_page beside next_cursor before requesting another page. Use sinceTime and untilTime for a bounded collection window. Use list_post_extractor for a saved CSV, JSON, or XLSX export.

Why are some Twitter list tweets missing?

First, check includeReplies. The default excludes replies. Then verify any sinceTime and untilTime boundaries. Visibility also depends on the connected read context. X says protected posts remain visible only to approved followers. Private Lists owned by other accounts are not visible. Read X’s official Help with Lists for current visibility rules. Remaining credits can reduce a paid page. New posts can also shift a moving timeline between requests. A missing Tweet does not prove deletion.

Can this endpoint create or edit a Twitter list?

No. This route only reads List tweets. It cannot create a public List or private List. It cannot add members, remove members, follow Lists, or publish posts. Use X’s Lists guide to create and manage Lists. Use the List Members endpoint for the current profile roster.

How do I measure activity in a curated list timeline?

Group rows by stable author ID. Count Tweets, replies, reposts, likes, quotes, views, and media items separately. Store every count with its collection time. These measures describe captured List tweets. They do not expose unique viewers, link clicks, conversions, or audience sentiment.

Does the API preserve list tweet order?

Preserve the returned Tweet sequence in every page. Do not treat that order as permanent. New posts and membership changes can shift later requests. Record collection time, List ID, and cursor with every page. Deduplicate retries by stable Tweet ID without re-ranking the saved rows.
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
The Node.js & Python snippets shape one durable row per returned list tweet instead of printing the full response page. Persist the final next_cursor row when has_next_page is true, then pass it back as cursor for the next page.

Direct list tweet handoff

Use GET /x/lists/{id}/tweets when a CRM, warehouse, newsroom, monitoring job, or agent needs tweets from a curated X List. Store list_id, tweet_id, text, author_id, author_username, author_name, author_followers, author_verified, author_profile_picture, created_at, engagement counts, & media_urls for each row. Keep has_next_page & next_cursor with the export checkpoint so the next run can resume the list timeline without duplicating earlier rows. Use sinceTime & untilTime for bounded backfills, and set includeReplies=true only when reply tweets belong in the downstream queue.

List tweet rows

Store tweets[] as timeline rows from accounts in the list. Use the row shape above for newsroom, monitoring, CRM, and warehouse imports.

Next page

Store has_next_page and next_cursor. Only request another page when has_next_page is true.

Default page

Direct calls use the default paid tweet page size. Treat the returned tweets.length as the row count returned for this page.

Time window

Use sinceTime and untilTime for bounded backfills or repeat sync jobs.

Reply filter

Leave includeReplies unset for a cleaner list timeline. Set includeReplies=true only when reply tweets belong downstream.

Saved export

Use list_post_extractor when the workflow needs a saved job with CSV/JSON/XLSX output.

Build a curated-list tweet feed

Use list tweets when a list ID defines the source accounts. Keep the list ID and collection time with every tweet. Save tweet ID, text, author, creation time, engagement counts, media URLs, and cursor. Preserve the author ID because list membership can change later. Use this feed for research queues, newsroom monitoring, or account-group review. It represents tweets from curated list members, not tweets mentioning the list. Deduplicate pages by list ID and tweet ID. Persist each page before advancing its cursor. New posts can shift the first page between runs. Use list members for the curated profile roster. Use list followers for the list’s audience. Use tweet search when keywords should define the result set.

Path parameters

string
required
List ID (numeric string).

Query parameters

string
Pagination cursor from a previous response. Omit for the first page.
integer
Tweets per page. Range: 1-100. Defaults to 20.
string
Unix timestamp in seconds. Only return tweets after this time.
string
Unix timestamp in seconds. Only return tweets before this time.
boolean
Include reply tweets. Default: false.

Which list endpoint?

List tweets

Use GET /x/lists/{id}/tweets for tweets from accounts in the list.

List members

Use GET /x/lists/{id}/members for accounts the list owner added to the list.

List followers

Use GET /x/lists/{id}/followers for accounts that follow the list.

Bulk list jobs

Use Create extraction with list_post_extractor, list_member_extractor, or list_follower_explorer when the workflow needs a saved export.

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 from the list. Tweet object fields.
string
Tweet ID.
string
Contains the complete Tweet text.
string
Classifies the Tweet when X returns a type.
string
ISO 8601 creation timestamp.
boolean
Whether this is a Note Tweet. Omitted if unavailable.
number
Reports the number of likes when available.
number
Reports the number of reposts when available.
number
Reports the number of replies when available.
number
Reports the number of quotes when available.
number
Reports the number of views when available.
number
Reports the number of bookmarks when available.
string
Permalink URL on X. Omitted if unavailable.
string
Reports the Tweet language code when available.
boolean
Whether the tweet is a reply. Omitted if unavailable.
string
Tweet ID being replied to. Omitted if not a reply.
string
Identifies the replied-to user when available.
string
Reports the replied-to username when available.
string
Conversation thread ID. Omitted if unavailable.
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
Returns paid-promotion and AI-generated-media labels when available. Includes advertising.isPaidPromotion and aiGenerated.hasAiGeneratedMedia.
object
Tweet author profile. Omitted if unavailable. Author object fields.
string
Author user ID.
string
Author X username.
string
Author display name.
number
Reports the author’s follower count when available.
boolean
Whether the author is verified. Omitted if unavailable.
string
Profile picture URL. Omitted if unavailable.
object[]
Lists media items attached to the Tweet. Omitted when none exist. Media object fields.
string
Provides the direct media URL.
object[]
Lists available video renditions and playback details. Omitted for images.
string
Identifies the attached 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. Pass as the cursor query parameter.

400 Invalid list ID

The list ID path parameter is empty.

401 Unauthenticated

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

402 Payment required

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

404 List not found

The list could not be resolved. Check the list ID.

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.