Skip to main content
GET
Twitter media scraper & profile export API guide
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 result returned · All plans from $0.00012/credit · Supports guest paid reads

User media handoff

Use GET /x/users/{id}/media when a gallery, moderation queue, warehouse, or agent needs recent media tweets from one account. The examples above write JSON Lines rows with the source user, media tweet ID, text, tweet URL, author ID, username, display name, follower count, verified state, profile image URL, engagement counts, media_urls, media_types, and cursor fields so a worker can resume from the last saved next_cursor.

Which media endpoint?

  • Use GET /api/v1/x/users/{id}/media when every row must be a media tweet from one profile. Store media_urls, media_types, media_tweet_id, page_cursor, next_cursor, and has_next_page.
  • Use GET /api/v1/x/users/{id}/tweets when the sync also needs non-media posts or replies.
  • Use GET /api/v1/x/tweets/{id} when you already know one tweet ID and need its media plus full tweet detail.
  • Use POST /api/v1/x/media only to host or validate a local file or HTTPS media URL before a write. Pass mediaUrl to POST /api/v1/x/tweets, or pass mediaId as the only media_ids item for POST /api/v1/x/dm/{userId}.

Build a profile media inventory

Use this route for tweets containing photos, videos, or animated GIFs from one profile. Keep the source profile ID with every media item. Record both tweet and media fields:
  • Tweet ID, text, author, and creation time.
  • Media type and media URL.
  • Video variants when present.
  • Engagement counts and page cursor.
One tweet can contain several media items. Preserve the tweet-to-media relationship. Do not flatten several URLs into an ambiguous single value. Use the inventory for asset review, campaign research, or approved archiving. Respect the original publisher and applicable usage rights. Deduplicate tweets by tweet ID. Deduplicate individual assets by their media URL within that tweet. Save each page before advancing the cursor. Use user likes for tweets the profile liked. Use user tweets for the complete profile timeline. Use download media only after selecting a specific asset.

Hand media into an asset workflow

Create one child row per media item. Include the parent tweet ID, media type, source URL, author ID, and collection time. Choose the best available video variant only after inspecting its metadata. Keep the original variant list when later processing may need another format. Do not download every asset during discovery. First filter and approve the relevant tweets. Then call the download route for selected media. Preserve attribution and source links in any archive. The media URL alone does not explain who published the asset or where it appeared. Record download status separately from discovery status. A listed media URL does not mean the asset was downloaded. Keep failed downloads retryable by tweet ID and media URL. Do not rerun the entire profile export for one failed asset.

Path parameters

string
required
X user ID (numeric string) or username.

Query parameters

string
Pagination cursor. Pass the next_cursor value from the previous response to fetch the next page.
integer
Tweets per page. Range: 1-100. Defaults to 20.

Tweet result filters

These optional filters apply to tweets[] returned by this route. They keep the same media-tweets target and filter rows after each page is fetched, so 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 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.
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 containing media. 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. 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.
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 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

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

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.