Migrate

Comparing X API's timelines endpoints

The v2 reverse chronological timeline, user Posts timeline, and user mention timeline endpoints replace the v1.1 statuses/home_timeine, v1.1 statuses/user_timeline, and v1.1 statuses/mentions_timeline endpoints respectively. If you have code, apps, or tools that use an older version of this endpoint and are considering migrating to the newer X API v2 endpoint, then this guide is for you.  For a more in-depth migration guide see Standard v1.1 migration to X API v2.

This page contains three comparison tables:

  • Reverse chronological home timeline
  • User Post timeline
  • User mention timeline

 

Reverse chronological home timeline

The following tables compare the standard v1.1 and X API v2 home timeline endpoints:

 

Description

Standard v1.1

X API v2

Documentation

API Reference

API Reference

HTTP methods supported

GET

GET

Host domain

https://api.x.com

https://api.x.com

Endpoint paths

/1.1/statuses/home_timeline.json

/2/users/:id/timelines/reverse_chronological

Required parameters

user_id or screen_name

User ID set as path parameter :id

Authentication

OAuth 1.0a User Context

 

OAuth 1.0a User Context

OAuth 2.0 Authorization Code Flow with PKCE

Request rate limits/Volume limits

15 requests per 15-minute with OAuth 1.0a User Context

Request cap: 100,000 within a 24 hour period.

180 requests per 15-minute window 

Post cap:

500,000 when using Essential access

2 million when using Elevated access

10 million when using Academic Research access

Default Posts per response

15

100

Maximum Posts per response

800

This endpoint returns every Post created on a timeline over the last 7 days as well as the most recent 800 regardless of creation date.

Provides Post edit history

Historical Posts available

The most recent 800 Posts, including Retweets

The most recent 3,200 Posts, including Retweets

Timeline navigation options

since_id (exclusive) used for update polling

max_id (inclusive)

start_time

end_time

since_id(exclusive) used for update polling 

until_id (exclusive) 

Optional parameters for results refinement

count

exclude_replies

include_rts

trim_user

tweet_mode

since_id

max_id

max_results

exclude(retweets,replies)

tweet.fields

user.fields

place.fields

media.fields

poll.fields

expansions

start_time

end_time

since_id

until_id

Supports requesting and receiving annotations

N/A

If annotations are included in tweet.fields, results will be annotated with inferred annotation data based on the Post text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton'

Supports requesting and receiving specific Post metrics

N/A

If annotations are included in tweet.fields, results will be annotated with public_metrics per Post including retweet_count, reply_count, quote_count and like_count, non_public_metrics , including impression_count, user_profile_clicks, url_link_clicks.

Additional media metrics such as view_count and video playback metrics.

Additional organic_metrics and promoted_metrics available with User Context for promoted Posts.

Supports requesting and receiving conversation_id

N/A

Returns a conversation_id field where the value represents the first published Post in a reply thread to help you track conversations. 

Post JSON format

Standard v1.1 data format

X API v2 format (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our data formats migration guide.

Results order

Reverse chronological

Reverse chronological

Results pagination

N/A must use navigation by Post ID

Results can be reviewed moving forward or backward using a pagination_token

Requires the use of credentials from a developer App associated with a Project

 

User Post timeline

The following tables compare the standard v1.1 and X API v2 user Post timeline endpoints:

Description Standard v1.1 X API v2
Documentation API Reference API Reference
HTTP methods supported GET GET
Host domain https://api.x.com https://api.x.com
Endpoint paths /1.1/statuses/user_timeline.json
/2/users/:id/tweets
Required parameters

user_id or screen_name

User ID set as path parameter :id
Authentication

OAuth 1.0a User Context

OAuth 2.0 App-Only

OAuth 1.0a User Context

OAuth 2.0 App-Only

OAuth 2.0 Authorization Code with PKCE

Request rate limits/Volume limits

900 requests per 15 min with OAuth 1.0a User Context

1500 requests per 15 min with OAuth 2.0 App-Only

Request cap: 100,000 within a 24 hour period.

900 requests per 15-minute window with OAuth 1.0a User Context

1500 requests per 15-minute window with OAuth 2.0 App-Only

Post cap:
500,000 when using Essential access
2 million when using Elevated access
10 million when using Academic Research access

Default Posts per response 15 10
Maximum Posts per response 200 100
Historical Posts available The most recent 3,200 Posts, including Retweets The most recent 3,200 Posts, including Retweets
Timeline navigation options

since_id (exclusive) used for update polling

max_id (inclusive)

start_time

end_time

since_id (exclusive) used for update polling 

until_id (exclusive) 

Optional parameters for results refinement count
exclude_replies
include_rts
trim_user
tweet_mode
since_id
max_id
max_results
exclude(retweets,replies)
tweet.fields
user.fields
place.fields
media.fields
poll.fields
expansions
start_time
end_time
since_id
until_id

Supports requesting and receiving annotations

N/A Returns Post results with inferred annotation data based on the Post text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton'

Supports requesting and receiving specific Post metrics

N/A

Returns Post results with available public_metrics per Post including retweet_count, reply_count, quote_count and like_count.

Available with OAuth1.0a User Context:
Additional non_public_metrics , including impression_count, user_profile_clicks, url_link_clicks.

Additional media metrics such as view_count and video playback metrics.

Additional organic_metrics and promoted_metrics available with OAuth 1.0a User Context for promoted Posts.

Supports requesting and receiving conversation_id N/A Returns a conversation_id field where the value represents the first published Post in a reply thread to help you track conversations. 
Post JSON format Standard v1.1 data format

X API v2 format (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our data formats migration guide.

Results order Reverse chronological Reverse chronological
Results pagination N/A must use navigation by Post ID
Results can be reviewed moving forward or backward using a pagination_token
Requires the use of credentials from a developer App associated with a Project  
Provides Post edit history


 

User mention timeline

The following tables compare the standard v1.1 and X API v2 user mention timeline endpoints

Description Standard v1.1 X API v2
Documentation API Reference API Reference
HTTP methods supported GET GET
Host domain https://api.x.com https://api.x.com
Endpoint paths /1.1/statuses/mentions_timeline.json /2/users/:id/mentions
Required parameters

no required parameters

User ID set as path parameter :id
Authentication

OAuth 1.0a User Context

OAuth 1.0a User Context

OAuth 2.0 App-Only

OAuth 2.0 Authorization Code with PKCE

Default request rate limits

75 requests per 15 min with OAuth 1.0a User Context

100,000 request cap within a 24 hour period.

180 requests per 15-minute window with OAuth 1.0a User Context

450 requests per 15-minute window with OAuth 2.0 App-Only

Post cap:

500,000 when using Essential access
2 million when using Elevated access
10 million when using Academic Research access

Default Posts per response 15 10
Maximum Posts per response 200 100
Historical Posts available The most recent 800 Posts The most recent 800 Posts
Timeline navigation options

since_id (exclusive) used for update polling

max_id (inclusive)

start_time

end_time

since_id (exclusive) used for update polling

until_id (exclusive)

Optional parameters for results refinement count
trim_user
include_entities
tweet_mode
since_id
max_id
max_results
tweet.fields
user.fields
place.fields
media.fields
poll.fields
expansions
start_time
end_time
since_id
until_id

Supports requesting and receiving annotations

N/A Returns Posts results with inferred anotation data based on the Post text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton'

Supports requesting and receiving specific Post metrics

N/A

Returns Post results with available public_metrics per Post including retweet_countreply_countquote_count and like_count.

Available with OAuth 1.0a User Context:
Additional non_public_metrics , including impression_countuser_profile_clicksurl_link_clicks

Additional media metrics such as view_count and video playback metrics.

Additional organic_metrics and promoted_metrics available with OAuth 1.0a User Context for promoted Posts

Supports requesting and receiving conversation_id N/A Returns a conversation_id field where the value represents the first published Post in a reply thread to help you track conversations. 
Post JSON format Standard v1.1 data format

X API v2 format (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our data formats migration guide.

Results order Reverse chronological Reverse chronological
Request parameters for pagination N/A must use navigation by Post ID
Results can be reviewed moving forward or backward using pagination_token
Requires the use of credentials from a developer App associated with a Project  
Provides Post edit history