Skip to main content
GET
Search user tweets, profile timeline & cursors
Repost records include retweetedAt, the repost event’s UTC ISO 8601 timestamp. It is null when that timestamp is unavailable. The API omits it for original posts. The nested original post keeps its own creation date. This field does not report every account that reposted a post. Request per-account timestamps with Get retweeters.
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.
Existing unprefixed cursors keep their legacy behavior. 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. First-page requests do not support Idempotency-Key retries. Repeating a cursorless request starts a separate extraction. Results returned by that extraction incur their normal charges. Save each response before requesting its next page. You cannot replay earlier or terminal responses after their cursors become unavailable. 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. Repeated busy responses never authorize restarting with another cursor. Finished, expired, superseded, or identity-mismatched cursors return 410 coverage_cursor_gone. The response omits Retry-After. Restart without a cursor. Keep received results. Deduplicate restarted results by id. Malformed cursors return 400 invalid_coverage_cursor. Restart without them. This route returns the public profile timeline for one Twitter or X account. The route is GET /api/v1/x/users/{id}/tweets. Protected accounts return HTTP 403 with x_account_protected. Choose a public account. This applies to every mode, including continuation requests. Xquik collects no results and charges nothing. Public profile lookup remains available.

User timeline handoff

Use GET /x/users/{id}/tweets when a CRM, queue worker, or warehouse job needs one user’s profile timeline. This endpoint accepts a username or numeric user ID. It 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. A worker can then resume from the last saved next_cursor. For high-volume timeline pulls, deduplicate tweets by id. Continue through empty filtered pages while the cursor advances. Stop with a partial-result status when next_cursor is missing or repeats.

Build a profile timeline job

Choose profile posts, reply context, media filters, or saved cursors.

Original posts

Set replies=exclude to fetch the profile timeline without replies. Own-thread replies stay.

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}/tweets for one user’s profile timeline. It returns original profile posts by default.
  • Add includeReplies=true when the sync needs replies. Add includeParentTweet=true when reply rows need parent context.
  • Use GET /api/v1/x/users/{id}/replies when every page should include replies by default.
  • Use GET /api/v1/x/users/{id}/media when every returned row should contain profile media.
  • Use GET /api/v1/x/users/{id}/highlights for the posts on the Highlights tab.
  • Use GET /api/v1/x/tweets/search for keyword, operator, or advanced search.
  • Use GET /api/v1/x/timeline for 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.
Use tweet search when the workflow starts with keywords, dates, or operators. Use user replies when replies need their own feed. Use user media when only photo, video, or animated GIF tweets matter. Row order does not identify a tweet. New tweets can change the first page. Use tweet IDs for updates and deduplication. The first page opens with the pinned tweet, flagged isPinned, as x.com shows it. Later pages skip it. With replies included, it never opens the page. Rows stay in newest-first date order on every page. x.com’s Posts tab differs: it groups each self-thread root first and hides reposts. Pass retweets=exclude to drop reposts.

Path parameters

string
required
User ID, username with or without @, or URL-encoded profile URL, such as x.com/nasa. See path 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.
string
Omit it for automatic maximum coverage. Use standard for legacy pagination. Search filters such as keywords apply only without it.
number
default:"20"
Automatic pages accept 1 through 300. Unprefixed legacy cursors accept 1 through 100. Source availability, filters, or credits can return fewer.
string
Keep posts created at or after this time. Send ISO 8601, such as 2026-09-25T19:20:41Z, or Unix seconds. A time without an offset is UTC.
string
Keep posts created before this time, in the same formats. With sinceDate or untilDate, the narrower window applies.
boolean
default:"false"
Include reply tweets. Default: false. Explicit replies takes precedence.When you exclude replies, the author’s replies to their own posts stay. They continue a thread, and X shows them on the Posts tab.
boolean
default:"false"
Include parent tweet context for returned replies. Defaults to false. Set it to true when replies need conversation context. Search filters such as keywords do not apply with it.

Tweet result filters

These optional filters apply to tweets[] returned by this route. They keep the same user target. Xquik filters rows after it fetches each page. Selective filters can return fewer rows than an unfiltered page.
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 up to this date or timestamp. A date is a UTC day, inclusive, so its own posts count.
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. This setting overrides includeReplies when the endpoint supports both.
string
Use include, exclude, or only for reposts.
string
Match this literal phrase, including any hyphens.
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.
string
Keep only Tweets with this card type, such as poll2choice_text_only. Tweet search checks each Tweet’s card.
string
X search no longer supports source. A Tweet search with it answers 424 & charges nothing.
string
X search no longer supports excludeSource. A Tweet search with it answers 424 & charges nothing.
string
X search no longer supports geocode. A Tweet search with it answers 424 & charges nothing.
string
Match this place name.
string
X search no longer supports within. A Tweet search with it answers 424 & charges nothing. Use near alone.
boolean
When true, enable X safe-search filtering.
boolean
X no longer searches filter:news, so leave this unset.
string
Return Tweets whose IDs exceed this ID.
string
Return Tweets at or below this ID.
boolean
When true, only return native reposts.
string
Match Tweets from this recent window, such as 90m or 7d. Use a whole number & s, m, h or d.
string
Words the Tweets must match, in X search syntax.
string
Search within this X place ID. Search places finds the ID by name.
string
Search within this country code.
string
Geo point radius in X search syntax, such as -73.99 40.73 25mi.
string
Geo bounding box in X search syntax, such as -74.1 40.6 -73.9 40.8.
string
Raw X search operators appended to the final search query.
string
Search within this X List 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 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.
boolean
Whether the author pinned this post to their profile. 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.
boolean
Whether this row is a retweet. text carries the original post in full.
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[]
Media attachments. Omitted if unavailable. Media item 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
Opaque cursor for the next page. Empty string when no more results.

400 Invalid user ID

The user ID is empty or invalid.

404 User not found

The username or user ID doesn’t resolve.

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.

502 X API unavailable

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

429 Rate limit exceeded

You exceeded your tier rate limit. 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.