Comparing Twitter API's timelines endpoints

The v2 user Tweets timeline and user mention timeline endpoints will eventually replace the 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.

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

User Tweet timeline

Description v1.1 user_timeline Twitter API v2 user Tweets Timeline
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 1.0a Bearer Token

OAuth 1.0a User Context

OAuth 2.0 Bearer Token

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 Bearer Token

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 Bearer Token

Tweets consumed count toward volume cap: 500,000 Tweets per Project within a monthly period.

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 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.

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 avialble with OAuth1.0a User Context for promoted Tweets
Supports requesting and receiving conversation_id N/A Returns Tweet results including the Tweet ID of the initiating conversation (for replies)
Tweet JSON format v1.1 data format

Twitter API v2 format (determined by fields and expansions request parameters)

*not backward-compatible with v1.1 formats

Results object format

  [

    {tweet object},

    {tweet object}

  ]

{

"data": [{id,text},{id,text}],

"meta": {

"oldest_id": "1337085692623646724",

"newest_id": "1334183616172019713",

"previous_token": "77qpymm88g5h9vqkluldpw91lr0qzfz1sqydh841iz48k",

"result_count": 10,

"next_token": "7140dibdnow9c7btw3w29gqolns6a1ipl3kzeae41vsxk"

}

}

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
Roadmap plan Pending Deprecation/Retirement date  Currently on version 2, pending updates in future Twitter API versions. Have feedback? Let us know.


 

User mention timeline

Description v1.1 mentions_timeline Twitter API v2 user mentions timeline
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 Bearer Token

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 Bearer Token

Tweets consumed count toward volume cap: 500,000 Tweets per Project within a monthly period.

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_countreply_countquote_count and like_count.

Available with OAuth1.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 avialble with OAuth1.0a User Context for promoted Tweets
Supports requesting and receiving conversation_id N/A Returns Tweet results including the Tweet ID of the initiating conversation (for replies)
Tweet JSON format v1.1 data format

Twitter API v2 format (determined by fields and expansions request parameters)

*not backward-compatible with v1.1 formats

Results object format

  [

    {tweet object},

    {tweet object}

  ]

{

"data": [{id,text},{id,text}],

"meta": {

"oldest_id": "1337085692623646724",

"newest_id": "1334183616172019713",

"previous_token": "77qpymm88g5h9vqkluldpw91lr0qzfz1sqydh841iz48k",

"result_count": 10,

"next_token": "7140dibdnow9c7btw3w29gqolns6a1ipl3kzeae41vsxk"

}

}

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
Roadmap plan Pending Deprecation/Retirement date  Currently on version 2, pending updates in future Twitter API versions.  Have feedback? Let us know.

 

Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.