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 |
||
HTTP methods supported |
|
|
Host domain |
|
|
Endpoint paths |
|
|
Required parameters |
|
User ID set as path parameter :id |
Authentication |
OAuth 1.0a User Context
|
OAuth 1.0a User Context |
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 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
|
end_time
|
Optional parameters for results refinement |
|
|
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 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 |
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.twitter.com | https://api.twitter.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: |
| 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. 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.twitter.com | https://api.twitter.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 500,000 when using Essential 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. 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 | ✔ | ✔ |