Tweets
Search User Tweets, Profile Timeline & Cursors
Search one Twitter or X profile’s tweets with full text, replies, reposts, likes, quotes, views, attached media, and cursor pagination. See API fields.
- 200
- 400
- 401
- 402
- 404
- 409
- 410
- 424
- 429
- 502
- 503
GET
Search User Tweets, Profile Timeline & Cursors
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
Omit
mode for automatic maximum coverage. Xquik combines available views
within a short request window. It keeps the existing response shape.
Pass next_cursor back unchanged as cursor. Keep the same endpoint, target,
query, and filters.after, limit, and
pageSize aliases also keep working. Billing still counts only returned rows.
Use mode=standard only to force legacy single-view pagination.
A page can be empty or underfilled. Continue while has_next_page is true.
Stop only after the response reports has_next_page=false.
If automatic coverage is busy, an initial request returns a standard data page.
Live coverage cursors remain atomic. Concurrent use returns
409 coverage_cursor_unavailable with exact Retry-After seconds. Wait, then
retry the same cursor once.
Finished, expired, superseded, or identity-mismatched cursors return
410 coverage_cursor_gone. The response omits Retry-After. Restart without
a cursor. Deduplicate restarted results by id.
Malformed cursors return 400 invalid_coverage_cursor. Restart without them.
Search user tweets returns the public profile timeline for one Twitter or X
account. Use it for “user tweets,” “profile timeline,” or “X user timeline”
searches. Keep the canonical route as
GET /api/v1/x/users/{id}/tweets.User timeline handoff
UseGET /x/users/{id}/tweets when a CRM, queue worker, or warehouse job needs
one user’s profile timeline. This endpoint accepts either a username or numeric
user ID and returns recent public posts from that profile.
The examples above write JSON Lines rows with the source profile, tweet ID,
text, author ID, username, display name, follower count, verified state, profile
image URL, reply context, engagement counts, media URLs, and cursor fields so a
worker can resume from the last saved next_cursor.
For high-volume timeline pulls, de-duplicate tweets by id, continue through empty filtered pages when the cursor advances, and stop with a partial-result status when next_cursor is missing or repeats.
Build a profile timeline job
Use these checkpoints when a timeline sync needs to switch between plain profile posts, replies, media-only rows, and resumable page pulls.Original posts
Omit
includeReplies to fetch the profile timeline without replies.Replies with context
Set
includeReplies=true and includeParentTweet=true when support,
community, or research rows need the parent tweet context.Media timeline
Use a
mediaType filter for filtered timeline rows, or switch to
User media when every row should contain
media.Cursor checkpoint
Store
page_cursor, next_cursor, and has_next_page before requesting
another page.Which timeline endpoint?
- Use
GET /api/v1/x/users/{id}/tweetsfor one user’s profile timeline. It returns original profile posts by default. - Add
includeReplies=truewhen the sync needs replies, and addincludeParentTweet=truewhen reply rows need parent context. - Use
GET /api/v1/x/users/{id}/replieswhen every page should include replies by default. - Use
GET /api/v1/x/users/{id}/mediawhen every returned row should contain profile media. - Use
GET /api/v1/x/tweets/searchfor keyword, operator, or advanced search. - Use
GET /api/v1/x/timelinefor the authenticated account’s home timeline.
Archive tweets from one profile
Use this user-tweets route when the source profile is already known. It fits profile timeline exports, account research, and approved historical backfills. Keep the source username or user ID beside every tweet. Export tweet ID, text, creation time, author fields, engagement counts, and media URLs. Save the cursor and collection time for each page. For a repeatable profile timeline:- Resolve the profile to a numeric user ID.
- Choose a stable page size.
- Save each page before its next cursor.
- Deduplicate resumed rows by tweet ID.
- Stop when no next page remains.
Path parameters
string
required
X username or numeric user ID. Use a username such as
elonmusk when the
profile handle is known, or a numeric ID such as 44196397 when you store
stable user IDs.Query parameters
string
Pagination cursor for the profile timeline. Omit it for the first page, then
pass the
next_cursor value from the previous response to fetch the next
page.number
default:"20"
Automatic pages accept
1 through 300. Unprefixed legacy cursors accept
1 through 100. Source availability, filters, or credits can return fewer.boolean
default:"false"
Include reply tweets in the profile timeline. Defaults to
false, which
returns original profile posts without replies.boolean
default:"false"
Include parent tweet context for returned replies. Defaults to
false; set it
to true when replies need conversation context.Tweet result filters
These optional filters apply totweets[] returned by this route. They keep the
same user target and filter rows after each page is fetched, so selective
filters can return fewer rows than an unfiltered page.
string
Filter to tweets authored by this username. The
@ prefix is optional.string
Filter to replies directed to this username.
string
Filter to tweets that mention this username.
string
Only include tweets with this language code, such as
en, tr, or es.string
Filter to tweets created on or after this date or timestamp.
string
Filter to tweets created before this date or timestamp. A
YYYY-MM-DD value includes the whole day before the boundary.string
Filter by attached media or links. Values:
images, videos, gifs, media, links, none.integer
Only include tweets meeting this minimum like count.
integer
Only include tweets meeting this minimum repost count.
integer
Minimum reply count.
integer
Minimum quote count.
integer
Minimum Tweet view count.
integer
Minimum Tweet bookmark count.
integer
Maximum Tweet like count. Tweets without a count pass this filter.
integer
Maximum Tweet repost count. Tweets without a count pass this filter.
integer
Maximum Tweet reply count. Tweets without a count pass this filter.
integer
Maximum Tweet quote count. Tweets without a count pass this filter.
boolean
When
true, only return Tweets from Blue-verified authors.boolean
When
true, only return tweets from verified authors.string
Set
include, exclude, or only for reply tweets.string
Set
include, exclude, or only for reposts.string
Set
include, exclude, or only for quote tweets.string
Exact text that must appear in the tweet.
string
Words or quoted phrases to exclude from returned tweets. Use commas or
whitespace between values.
string
Words or quoted phrases where at least 1 term must appear. Use commas or
whitespace between values.
string
Only include tweets matching these hashtags. Use commas or whitespace
between values. The
# prefix is optional.string
Only include tweets matching these cashtags. Use commas or whitespace
between values. The
$ prefix is optional.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.
string
Match the Tweet card name.
string
Match the source application.
string
Exclude Tweets from this source application.
string
Match latitude, longitude, and radius in X search syntax.
string
Return Tweets newer than this Tweet ID.
string
Return Tweets older than this Tweet ID.
string
Match this place name.
string
Set the radius for the
near filter.string
Match Tweets inside this recent time window.
boolean
When
true, only return native reposts.boolean
When
true, enable X safe-search filtering.boolean
When
true, only return news results.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 by the user.
Tweet object fields:
string
Tweet ID.
string
Tweet text content.
string
Tweet type. Omitted if unavailable.
string
ISO 8601 creation timestamp. Omitted if unavailable.
boolean
Whether this is a Note Tweet (long-form post). 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 the tweet is a reply. Omitted if unavailable.
string
Tweet ID being replied to. Omitted if not a reply.
string
User ID being replied to. Omitted if not a reply.
string
Username being replied to. Omitted if not a reply.
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 (URLs, hashtags, mentions). 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 X username.
string
Author display name.
number
Follower count. Omitted if unavailable.
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
Opaque cursor for the next page. Empty string when no more results.
400 Invalid user ID
404 User not found
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.502 X API unavailable
429 Rate Limit Exceeded
Retry-After header before retrying.
424 Dependency Failed
Related: User replies timeline · User media · User likes · User mentions timeline
- 200
- 400
- 401
- 402
- 404
- 409
- 410
- 424
- 429
- 502
- 503
Search User Tweets, Profile Timeline & Cursors