Integration Guide

Key concepts and best practices for integrating Timelines endpoints

This guide covers the key concepts you need to integrate the Timelines endpoints into your application.

---

Authentication

Endpoint requirements

Endpoint	App-Only	User Context
User Posts timeline	✓	✓
User mentions timeline	✓	✓
Home timeline	—	✓ (required)

Private metrics

To access private metrics, you must authenticate on behalf of the Post author:

These fields require User Context authentication:

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics
• media.fields.non_public_metrics
• media.fields.promoted_metrics
• media.fields.organic_metrics

---

Fields and expansions

By default, responses include only id, text, and edit_history_tweet_ids. Request additional data:

Example request

cURL

shellscript

curl "https://api.x.com/2/users/123/tweets?\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Key fields

Field	Description
created_at	Post creation timestamp
public_metrics	Engagement counts
conversation_id	Thread identifier
context_annotations	Topic classifications
entities	Hashtags, mentions, URLs

Fields and expansions guide

Learn more about customizing responses

---

Pagination

Timelines return up to 100 Posts per request. Use pagination for larger result sets.

How it works

1. Make initial request with max_results
2. Get next_token from the meta object
3. Include pagination_token in next request
4. Repeat until no next_token is returned

Example

cURL

shellscript

# First request
curl "https://api.x.com/2/users/123/tweets?max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# Subsequent request with pagination token
curl "https://api.x.com/2/users/123/tweets?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Pagination guide

Learn more about pagination

---

Filtering results

Time-based filtering

Parameter	Description
start_time	Oldest Post timestamp (ISO 8601)
end_time	Newest Post timestamp (ISO 8601)
since_id	Return Posts after this ID
until_id	Return Posts before this ID

Exclude parameter

Remove specific Post types from results:

cURL

shellscript

curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Value	Effect
retweets	Exclude retweets
replies	Exclude replies

---

Volume limits

Each timeline has maximum retrieval limits:

Endpoint	Maximum Posts
User Posts timeline	3,200 most recent
User Posts (exclude=replies)	800 most recent
User mentions timeline	800 most recent
Home timeline	3,200 or 7 days

Requesting Posts beyond these limits returns a successful response with no data.

---

Post edits

Posts can be edited up to 5 times within 30 minutes. Timeline endpoints always return the most recent version.

Considerations

• Posts older than 30 minutes represent their final version
• Near-real-time use cases should account for potential edits
• Use Post lookup to verify final state if needed

Edit Posts fundamentals

Learn more about Post edits

---

Post metrics

Public metrics

Available for all Posts with App-Only or User Context authentication:

{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12
  }
}

Private metrics

Requires User Context authentication from the Post author:

• Only available for Posts from the last 30 days
• Only returned for Posts authored by the authenticated user
• Returns error for other users’ Posts

---

Edge cases

Non-public metrics and pagination

When requesting non-public metrics for Posts older than 30 days, you may receive a next_token with result_count: 0. To avoid this:

• Keep requests within the last 30 days
• Use max_results of at least 10

Promoted metrics for non-promoted Posts

Requesting promoted metrics for Posts that weren’t promoted returns an empty response. This is a known issue.

Truncated Retweet text

For Retweets with text over 140 characters, the text field is truncated. Use the referenced_tweets.id expansion to get the full text.

---

Next steps

Home timeline quickstart

Get a user’s home feed

Mentions quickstart

Get mentions for a user

API Reference

Full endpoint documentation

Pagination

Handle large result sets