Get user timeline

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

Get user timeline is the User Timeline API for a single public X profile. The same endpoint is also useful when you call it “user tweets,” “profile timeline,” or “X user timeline.” Keep the canonical route as GET /api/v1/x/users/{id}/tweets.

# Username profile timeline
curl https://xquik.com/api/v1/x/users/elonmusk/tweets \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

# Numeric user ID profile timeline
curl https://xquik.com/api/v1/x/users/44196397/tweets \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

# Replies and parent tweet context
curl -G https://xquik.com/api/v1/x/users/elonmusk/tweets \
  --data-urlencode "includeReplies=true" \
  --data-urlencode "includeParentTweet=true" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

# Page 2 - pass next_cursor from the previous response
curl -G https://xquik.com/api/v1/x/users/elonmusk/tweets \
  --data-urlencode "cursor=abc123" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

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 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.

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.

{
  "timeline_job_id": "profile-timeline-q2",
  "timeline_route": "GET /api/v1/x/users/{id}/tweets",
  "user_id_or_username": "elonmusk",
  "include_replies": true,
  "include_parent_tweet": true,
  "cursor_param": "cursor",
  "page_cursor": "",
  "next_cursor": "DAADDAABCgABF...",
  "has_next_page": true,
  "media_handoff_route": "GET /api/v1/x/users/{id}/media"
}

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, and add includeParentTweet=true when reply rows need parent context.
Use GET /api/v1/x/users/{id}/media when every returned row should contain profile media.
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.

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

cursor

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.

includeReplies

boolean

default:"false"

Include reply tweets in the profile timeline. Defaults to false, which returns original profile posts without replies.

includeParentTweet

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 to tweets[] 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.

fromUser

string

Filter to tweets authored by this username. The @ prefix is optional.

toUser

string

Filter to replies directed to this username.

mentioning

string

Filter to tweets that mention this username.

language

string

Filter by tweet language code, such as en, tr, or es.

sinceDate

string

Filter to tweets created on or after this date or timestamp.

untilDate

string

Filter to tweets created before this date or timestamp. A YYYY-MM-DD value includes the whole day before the boundary.

mediaType

string

Filter by attached media or links. Values: images, videos, gifs, media, links, none.

minFaves

integer

Minimum like count.

minRetweets

integer

Minimum retweet count.

minReplies

integer

Minimum reply count.

minQuotes

integer

Minimum quote count.

verifiedOnly

boolean

When true, only return tweets from verified authors.

replies

string

Reply mode. Values: include, exclude, only.

retweets

string

Retweet mode. Values: include, exclude, only.

quotes

string

Quote mode. Values: include, exclude, only.

exactPhrase

string

Exact text that must appear in the tweet.

excludeWords

string

Words or quoted phrases to exclude from returned tweets. Separate with spaces, commas, or lines.

anyWords

string

Words or quoted phrases where at least 1 term must appear in the tweet. Separate with spaces, commas, or lines.

hashtags

string

Hashtags to match. Separate with spaces, commas, or lines. The # prefix is optional.

cashtags

string

Cashtags to match. Separate with spaces, commas, or lines. The $ prefix is optional.

url

string

URL substring or domain that must appear in tweet URL entities.

conversationId

string

Filter to tweets in this conversation thread.

inReplyToTweetId

string

Filter to replies to this tweet ID.

quotesOfTweetId

string

Filter to quote tweets of this tweet ID.

retweetsOfTweetId

string

Filter to retweets of this tweet ID.

Headers

x-api-key

string

required

Your API key. Session cookie authentication is also supported.

Response

tweets

object[]

Array of tweets by the user.

Show tweet object

string

Tweet ID.

text

string

Tweet text content.

type

string

Tweet type. Omitted if unavailable.

createdAt

string

ISO 8601 creation timestamp. Omitted if unavailable.

isNoteTweet

boolean

Whether this is a Note Tweet (long-form post). Omitted if unavailable.

likeCount

number

Like count. Omitted if unavailable.

retweetCount

number

Retweet count. Omitted if unavailable.

replyCount

number

Reply count. Omitted if unavailable.

quoteCount

number

Quote tweet count. Omitted if unavailable.

viewCount

number

View count. Omitted if unavailable.

bookmarkCount

number

Bookmark count. Omitted if unavailable.

url

string

Permalink URL on X. Omitted if unavailable.

lang

string

Tweet language code. Omitted if unavailable.

isReply

boolean

Whether the tweet is a reply. Omitted if unavailable.

inReplyToId

string

Tweet ID being replied to. Omitted if not a reply.

inReplyToUserId

string

User ID being replied to. Omitted if not a reply.

inReplyToUsername

string

Username being replied to. Omitted if not a reply.

conversationId

string

Conversation thread ID. Omitted if unavailable.

source

string

Client used to post the tweet. Omitted if unavailable.

displayTextRange

number[]

Start and end offsets for rendered tweet text. Omitted if unavailable.

isLimitedReply

boolean

Whether replies are limited. Omitted if unavailable.

isQuoteStatus

boolean

Whether this tweet quotes another tweet. Omitted if unavailable.

entities

object

Parsed entities (URLs, hashtags, mentions). Omitted if unavailable.

author

object

Tweet author profile. Omitted if unavailable.

Show author object

string

Author user ID.

username

string

Author X username.

name

string

Author display name.

followers

number

Follower count. Omitted if unavailable.

verified

boolean

Whether the author is verified. Omitted if unavailable.

profilePicture

string

Profile picture URL. Omitted if unavailable.

media

object[]

Media attachments. Omitted if unavailable.

Show media item

mediaUrl

string

Direct media URL.

type

string

Media type.

url

string

Shortened URL from the tweet text.

quoted_tweet

object

Embedded quoted tweet. Omitted if not a quote tweet.

retweeted_tweet

object

Original retweeted tweet. Omitted if not a retweet.

has_next_page

boolean

Whether more results are available.

next_cursor

string

Opaque cursor for the next page. Empty string when no more results.

{
  "tweets": [
    {
      "id": "1893456789012345678",
      "text": "User's tweet content",
      "createdAt": "2026-02-24T10:00:00.000Z",
      "likeCount": 500,
      "retweetCount": 120,
      "replyCount": 45,
      "viewCount": 25000,
      "url": "https://x.com/elonmusk/status/1893456789012345678",
      "author": {
        "id": "44196397",
        "username": "elonmusk",
        "name": "Elon Musk",
        "followers": 150000000,
        "verified": true,
        "profilePicture": "https://pbs.twimg.com/profile_images/example.jpg"
      },
      "media": [{ "type": "photo", "mediaUrl": "https://pbs.twimg.com/media/example.jpg" }]
    }
  ],
  "has_next_page": true,
  "next_cursor": "DAADDAABCgABF..."
}

{ "error": "invalid_user_id", "message": "User not found or invalid user ID. Check the username or ID." }

The user ID is empty or invalid.

{ "error": "user_not_found", "message": "X user not found. Check the username." }

{ "error": "unauthenticated" }

Missing or invalid API key.

{ "error": "no_subscription" }

No active subscription or insufficient credits. Possible error values: no_subscription, subscription_inactive, no_credits, insufficient_credits. For MPP requests without a valid payment credential, 402 returns a WWW-Authenticate: Payment challenge header instead.

{ "error": "x_api_unavailable" }

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

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

Your tier rate limit was exceeded. Wait for the Retry-After header before retrying.

{ "error": "x_api_unavailable" }

The normalized v1 response contract can return 424 when the read service is unavailable.

Related: User media · User likes · User mentions timeline

Documentation Index

​User timeline handoff

​Build a profile timeline job

Original posts

Replies with context

Media timeline

Cursor checkpoint

​Which timeline endpoint?

​Path parameters

​Query parameters

​Tweet result filters

​Headers

​Response

User timeline handoff

Build a profile timeline job

Which timeline endpoint?

Path parameters

Query parameters

Tweet result filters

Headers

Response