Overview
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 pollingmax_id (inclusive) | start_timeend_time since_id(exclusive) used for update polling until_id (exclusive) |
| Optional parameters for results refinement | countexclude_repliesinclude_rtstrim_usertweet_modesince_idmax_id | max_resultsexclude(retweets,replies)tweet.fieldsuser.fieldsplace.fieldsmedia.fieldspoll.fieldsexpansionsstart_timeend_timesince_iduntil_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_count, reply_count, quote_count and like_count. Available with OAuth 1.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 |
| 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 | ✔ | ✔ |
Other migration resources