GET https://xquik.com/api/v1/x/timeline
Requested result counts are upper bounds for paid authenticated calls. Remaining credits may not cover the full page or ID list. If so, 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
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
Response
200 OK
401 Unauthenticated
Missing or invalid API key.402 Insufficient credits
Metered access requires enough available credits. Possible error values includeno_subscription, subscription_inactive, no_credits, and insufficient_credits.410 Cursor account unavailable
The X account that returned the cursor can no longer read. Request the first page again withoutcursor.429 Rate limit exceeded
The API key, user, or plan tier is sending requests too fast. Respect theRetry-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 returns424 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.
{ "error": "account_required", "message": "This read needs your own connected X account. Connect or restore it at dashboard.xquik.com/account, then retry." }Related. Notifications · Bookmarks
Response examples
- 400
{ "error": "invalid_input", "message": "Invalid input. Check the request body." } - 401
{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." } - 402
{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." } - 403
{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." } - 410
{ "error": "cursor_account_unavailable", "message": "The X account for this cursor is unavailable. Start again without the cursor." } - 424
{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." } - 429
{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 } - 502
{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." } - 503
{ "error": "x_api_unavailable", "message": "Xquik is busy right now. Retry shortly." }