Comparing Twitter API's timelines endpoints
The v2 reverse chronological timeline, user Tweets 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 Twitter API v2 endpoint, then this guide is for you. For a more in-depth migration guide see Standard v1.1 migration to Twitter API v2.
This page contains three comparison tables:
- Reverse chronological home timeline
- User Tweet timeline
- User mention timeline
Reverse chronological home timeline
The following tables compare the standard v1.1 and Twitter API v2 home timeline endpoints:
Description |
Standard v1.1 |
Twitter 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 Tweets per response |
15 |
100 |
Maximum Tweets per response |
800 |
This endpoint returns every Tweet created on a timeline over the last 7 days as well as the most recent 800 regardless of creation date. |
| Provides Tweet edit history | ✔ | ✔ |
Historical Tweets available |
The most recent 800 Tweets, including Retweets |
The most recent 3,200 Tweets, 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 Tweet text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton' |
Supports requesting and receiving specific Tweet 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 Tweets. |
Supports requesting and receiving conversation_id |
N/A |
Returns a conversation_id field where the value represents the first published Tweet in a reply thread to help you track conversations. |
Tweet JSON format |
Twitter 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 Twitter API v2 format, please visit our data formats migration guide. |
|
Results order |
Reverse chronological |
Reverse chronological |
Results pagination |
N/A must use navigation by Tweet 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 Tweet timeline
The following tables compare the standard v1.1 and Twitter API v2 user Tweet timeline endpoints:
| Description | Standard v1.1 | Twitter 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 Tweet cap: |
| Default Tweets per response | 15 | 10 |
| Maximum Tweets per response | 200 | 100 |
| Historical Tweets available | The most recent 3,200 Tweets, including Retweets | The most recent 3,200 Tweets, 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 Tweet results with inferred annotation data based on the Tweet text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton' |
Supports requesting and receiving specific Tweet metrics |
N/A | Returns Tweet results with available public_metrics per Tweet 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 Tweets. |
| Supports requesting and receiving conversation_id | N/A | Returns a conversation_id field where the value represents the first published Tweet in a reply thread to help you track conversations. |
| Tweet JSON format | Standard v1.1 data format | Twitter 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 Twitter API v2 format, please visit our data formats migration guide. |
| Results order | Reverse chronological | Reverse chronological |
| Results pagination | N/A must use navigation by Tweet 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 Tweet edit history | ✔ | ✔ |
User mention timeline
The following tables compare the standard v1.1 and Twitter API v2 user mention timeline endpoints
| Description | Standard v1.1 | Twitter 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 Tweets per response | 15 | 10 |
| Maximum Tweets per response | 200 | 100 |
| Historical Tweets available | The most recent 800 Tweets | The most recent 800 Tweets |
| 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 Tweet results with inferred anotation data based on the Tweet text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton' |
Supports requesting and receiving specific Tweet metrics |
N/A | Returns Tweet results with available public_metrics per Tweet 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 Tweets |
| Supports requesting and receiving conversation_id | N/A | Returns a conversation_id field where the value represents the first published Tweet in a reply thread to help you track conversations. |
| Tweet JSON format | Standard v1.1 data format | Twitter 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 Twitter 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 Tweet 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 Tweet edit history | ✔ | ✔ |