Lists
Twitter list tweets API & timeline export guide
Retrieve tweets from an X list with authors, text, replies, reposts, likes, quotes, media, timestamps, and cursor-based pagination. See request fields.
- 200
- 400
- 401
- 402
- 404
- 409
- 410
- 424
- 429
- 502
- 503
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.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. Storehas_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, checkincludeReplies. 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
next_cursor
row when has_next_page is true, then pass it back as cursor for the next
page.
Direct list tweet handoff
UseGET /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[]
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
401 Unauthenticated
Anonymous requests getWWW-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.404 List not found
502 X API unavailable
429 Rate limit exceeded
Retry-After header before retrying.
424 Dependency failed
Related. List Members · List Followers
- 200
- 400
- 401
- 402
- 404
- 409
- 410
- 424
- 429
- 502
- 503
Twitter list tweets API & timeline export guide