Home Timeline API

GET user/home_timeline returns the home timeline of the account tied to your registered session: the same ranked, most-recent-first feed that account sees on X's For You / Following tab. Each page returns full tweet objects with author and engagement counts, plus a cursor for pagination. It requires a registered session and costs $0.0008 per call.

curl -X GET "https://example.com/user/home_timeline?count=20&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1&paid_promotion=only"

{  "count": 1,  "next_cursor": "DAABCgABHL4VFSR__9oKAAIA...",  "tweets": [    {      "id": "2070410316496678962",      "text": "Bitcoin closed the daily candle above the key support.",      "created_at": "Fri Jun 26 07:34:20 +0000 2026",      "lang": "en",      "author": {        "id": "3185716686",        "username": "AshCrypto",        "name": "Ash Crypto",        "verified": true,        "followers_count": 2168823      },      "reply_count": 264,      "retweet_count": 309,      "favorite_count": 1277,      "quote_count": 11,      "bookmark_count": 24,      "view_count": 130944    }  ]}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use this endpoint to pull the ranked For You / Following feed shown to the account behind your registered session. Reach for a different User Reads endpoint when you need another account's public tweets (not the session account's personalized feed) or a single tweet's detail.

Notes

• Needs a registered session for the account you are reading (POST /customer/session). This endpoint does not accept per-call inline credentials: x-auth-token and x-ct0 headers are ignored here. Returns 409 session_required if no session is registered, 401 session_dead when the session has expired.
• Tweets with media carry an extended_entities.media array (see the Tweet model).

Pagination

This endpoint is cursor-paginated and returns roughly 20 records per call. Pass the next_cursor from each response back as the cursor parameter to read the next page. Stop when the records array comes back empty: follower-graph endpoints return a non-null cursor even on the final page, so the empty array is the only reliable stop signal. See Pagination for the full loop.

Related endpoints

• User Info by Username: Fetch a full profile by @handle.
• User Info by ID: Fetch a full profile by numeric user ID.

FAQ

Does this endpoint work for any Twitter/X account, or only my own?

Only the account behind your registered session. The endpoint has no user-id or username parameter, unlike endpoints that fetch another user's public tweets; it always returns the feed of the session that's currently registered with twitterapis.

How do I page through the full home timeline?

Each response includes next_cursor and has_more. Pass next_cursor as the cursor parameter on your next request to get the following page, and stop once has_more is false. count controls page size (default 20, max 100 per call).