Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.x.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through making your first request to the reverse chronological home timeline endpoint.
PrerequisitesBefore you begin, you’ll need:
  • A developer account with an approved App
  • User Access Tokens (this endpoint requires user authentication)

​
Step 1: Get the user ID

You need the user ID for the account whose home timeline you want to retrieve. Find it using the username lookup endpoint:
cURL
curl "https://api.x.com/2/users/by/username/XDevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"
The response includes the user ID: 
{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

​
Step 2: Request the home timeline

Make a GET request with the user ID and User Access Token:
cURL
curl "https://api.x.com/2/users/2244994945/timelines/reverse_chronological" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

​
Step 3: Review the response

{
  "data": [
    {
      "id": "1524796546306478083",
      "text": "Today marks the launch of Devs in the Details...",
      "edit_history_tweet_ids": ["1524796546306478083"]
    },
    {
      "id": "1524468552404668416",
      "text": "Join us tomorrow for a discussion about bots...",
      "edit_history_tweet_ids": ["1524468552404668416"]
    }
  ],
  "meta": {
    "result_count": 2,
    "newest_id": "1524796546306478083",
    "oldest_id": "1524468552404668416",
    "next_token": "7140dibdnow9c7btw421dyz6jism75z99gyxd8egarsc4"
  }
}

​
Step 4: Add fields and expansions

Request additional data with query parameters:
cURL
curl "https://api.x.com/2/users/2244994945/timelines/reverse_chronological?\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id&\
user.fields=username,verified&\
max_results=10" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

​
Step 5: Paginate through results

The SDKs handle pagination automatically. For cURL, use the next_token from the response to get more results: 
curl "https://api.x.com/2/users/2244994945/timelines/reverse_chronological?\
max_results=10&\
pagination_token=7140dibdnow9c7btw421dyz6jism75z99gyxd8egarsc4" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

​
Common parameters

ParameterDescriptionDefault
max_resultsResults per page (1-100)10
start_timeOldest Post timestamp (ISO 8601)—
end_timeNewest Post timestamp (ISO 8601)—
since_idReturn Posts after this ID—
until_idReturn Posts before this ID—
excludeExclude retweets, replies, or both—

​
Next steps

User mentions

Get Posts mentioning a user

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation

Pagination guide

Navigate large result sets