Skip to main content
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

Use GET /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 last next_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 the x-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. Render tweets[] 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. Respect Retry-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[]
Lists attached images, GIFs, or videos when available. Media item fields.
string
Returns the direct media URL.
object[]
Lists video renditions with bitrates, content types, and URLs.
string
Identifies the media type.
string
Returns the shortened URL from the tweet text.
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

Missing or invalid API key.

402 Insufficient credits

Metered access requires enough available credits. Possible error values include no_subscription, subscription_inactive, no_credits, and insufficient_credits.

429 Rate limit exceeded

The API key, user, or plan tier is sending requests too quickly. Respect the Retry-After header before retrying.

502 X API unavailable

The read service failed. Retry after a short delay.

424 Dependency failed

The opt-in normalized v1 contract returns 424 when the read service fails. Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.