Timeline & DMs
Twitter timeline API for home feed tweets & media
Get a connected X account’s home feed. Paginate tweets with authors, replies, reposts, likes, views, media, and cursors. Costs 1 credit per tweet returned.
- 200
- 401
- 402
- 410
- 424
- 429
- 502
- 503
GET
Twitter timeline API for home feed tweets & media
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
424 account_required. Use Connect X account
to add one. When your connected X accounts are busy, it returns 503. Retry
after the Retry-After delay.
Each next_cursor reads the next page from the same X account. If that account
can no longer read, the route returns 410 cursor_account_unavailable. Start
again without the cursor. An account that follows no one returns no tweets and
has_next_page: false.
Results exclude X ads.
Home timeline handoff
UseGET /x/timeline for the authenticated account’s home feed.
The examples write JSON Lines rows.
They include author ID, username, display name, and tweet text.
Rows include follower count, verified state, profile image URL, seenTweetIds, and cursor fields.
Store processed tweet IDs.
Then pass them as seenTweetIds with the last saved next_cursor.
Use the home timeline for inboxes, CRM routing, and approved monitoring. Store the connected
account ID and collection time with each page.
Keep tweet IDs, authors, text, engagement counts, replies, media, and
cursors. X controls ranking and source availability. The response
is not a complete public archive. X explains the feed model in its
home and user timeline documentation.
Home feed rows
Store one row per
tweets[] item with timeline_source: "home" for the
connected account.Seen tweet deduplication
Add processed tweet IDs to
seenTweetIds before requesting the next page.Cursor checkpoint
Store
has_next_page and next_cursor. Pass next_cursor back as cursor
only when has_next_page is true.Account-scoped sync
Keep home timeline rows in account-scoped inbox, CRM, monitor seed, or agent
memory systems.
Twitter API timeline pagination
Process one home-feed page at a time. Use each returned tweet ID to deduplicate timeline tweets. Save each page before advancing its cursor. Keep the prior cursor until validating its replacement. Send the lastnext_cursor as cursor after storing the full page. Pass
processed tweet IDs through seenTweetIds to reduce repeat rows. Stop when
has_next_page is false or next_cursor is empty.
Respect the Retry-After header after a 429 or 503 response.
After a 424 account_required response, connect an X account first.
After a 410 cursor_account_unavailable response, start again without the cursor.
After other 424 or 502 responses, retry the stored cursor.
Never advance a checkpoint after a failed destination write.
Route home timeline tweets
Keep each rule name beside its tweet ID. Keep the original tweet text.
Reprocess a tweet only after its routing rule changes.
Twitter timeline API questions
How do you authenticate timeline requests?
Send an Xquik API key through thex-api-key header. Keep keys server-side.
Never expose a key in a browser, mobile bundle, or public repository.
Can you filter home timeline tweets by hashtag?
No.GET /x/timeline returns the connected account’s ranked home feed. Use
tweet search for keyword, author, date, or media
filters.
Can you display timeline tweets in an app?
Yes. Rendertweets[] with the returned text, author, media, and tweet URL.
Store tweet IDs for deduplication. Refresh from the last confirmed cursor.
How should timeline API errors be retried?
Fix authentication after a 401 response. Add credits after a 402 response. Connect an X account after424 account_required. Start again without the
cursor after 410 cursor_account_unavailable. Respect Retry-After after 429
or 503. Resume from the stored cursor after other 424 or 502 responses.
Query parameters
string
Pagination cursor. Pass the
next_cursor value from the previous response to fetch the next page. The next page comes from the same connected X account.string
Comma-separated tweet IDs to exclude from results. Ignore empty entries. Use this to skip tweets the user has already seen.
Which timeline endpoint?
Home timeline
Use
GET /x/timeline for the connected account’s home feed.Profile timeline
Use
GET /x/users/{id}/tweets for one
public profile’s timeline.Mentions timeline
Use
GET /x/users/{id}/mentions for
public mentions of one account.Saved tweets
Use
GET /x/bookmarks for tweets the
connected account saved.Notifications
Use
GET /x/notifications for compact
inbox activity rows.Monitor events
Use
List events after account or keyword
monitors have captured replayable webhook events.Headers
string
required
Your API key. You can also authenticate with an OAuth bearer token.
Response
200 OK
object[]
Array of timeline tweets.
Tweet object fields.
string
Tweet ID.
string
Contains the tweet text.
string
Returns the tweet type when available.
string
Returns an ISO 8601 timestamp when available.
boolean
Marks long-form Note Tweets when available.
boolean
Whether the author pinned this post to their profile. Omitted if unavailable.
number
Counts likes when available.
number
Counts reposts when available.
number
Counts replies when available.
number
Counts quote tweets when available.
number
Counts views when available.
number
Counts bookmarks when available.
string
Links to the tweet on X when available.
string
Identifies the tweet language when available.
boolean
Marks replies when available.
string
Identifies the parent tweet for a reply.
string
Identifies the replied-to user.
string
Identifies the replied-to username.
string
Identifies the conversation when available.
string
Identifies the posting client when available.
number[]
Provides rendered text offsets when available.
boolean
Shows whether X limits replies.
boolean
Marks quote tweets when available.
boolean
Whether this row is a retweet.
text carries the original post in full.object
Returns parsed entities when available.
object
Describes paid partnerships and AI-generated media. Includes
advertising.isPaidPromotion and aiGenerated.hasAiGeneratedMedia when X returns them.object
Returns the tweet author when available.
Author object fields.
string
Identifies the author.
string
Returns the current X username.
string
Returns the display name.
number
Counts the author’s followers.
boolean
Shows whether X marks the author as verified.
string
Returns the profile image URL when available.
object[]
object
Embeds the quoted tweet when present.
object
Embeds the original repost when present.
boolean
Shows whether more tweets remain.
string
Provides the next page cursor. Empty after the final page.
401 Unauthenticated
402 Insufficient credits
no_subscription, subscription_inactive, no_credits, and insufficient_credits.
410 Cursor account unavailable
cursor.
429 Rate limit exceeded
Retry-After header before retrying.
502 X API unavailable
424 Dependency failed
424 when the read service fails.
Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.
Without a connected X account, the route returns 424 account_required. This
status needs no contract header.
Related. Notifications · Bookmarks