Timeline & DMs
Twitter timeline API for home feed tweets & media
Use the Twitter timeline API to get a connected account’s home feed. Paginate tweets, authors, replies, reposts, likes, views, media, and cursors safely.
- 200
- 401
- 402
- 424
- 429
- 502
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
Requires a connected X account. Uses user-authenticated access.
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.
This home timeline Twitter API workflow supports inboxes and CRM routing. A
Twitter API timeline also supports approved monitoring. Store the connected
account ID and collection time with each page.
Preserve tweet IDs, authors, text, engagement counts, replies, media, and
cursors. X controls ranking and source availability. Do not treat the response
as 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 dedupe
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
Use Twitter API timeline pagination to process each home-feed page. 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 response.
After a 424 or 502 response, 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. Preserve 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. RespectRetry-After after 429. Resume from the stored cursor after 424 or 502.
Query parameters
string
Pagination cursor. Pass the
next_cursor value from the previous response to fetch the next page.string
Comma-separated tweet IDs to exclude from results. Ignore empty entries. Use this to avoid returning 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.
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.
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.
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.
Related. Notifications · Bookmarks
- 200
- 401
- 402
- 424
- 429
- 502
Twitter timeline API for home feed tweets & media