Standard v1.1 timelines to Twitter API v2 timelines

If you have been working with the v1.1 timelines endpoints (statuses/user_timeline and statuses/mentions_timeline), the goal of this guide is to help you understand the similarities and differences between the standard and Twitter API v2 timelines endpoints, so that you can migrate your current integration to the new version.

  • Similarities:
    • Authentication Protocol:
      • OAuth 1.0a User Context (user Tweet timeline and user mentions timeline)
      • OAuth 2.0 Bearer Token (user Tweet timeline)
    • Historical Access limit: User timeline (user Tweet timeline) provides access to most recent 3200 Tweets; mentions timeline (user mention timeline) provides access to most recent 800 mentions
    • Rate limits (user Tweet timeline)
    • Refresh polling: Ability to retrieve new results since the since_id
    • Traversing timelines by Tweet IDs
    • Results specifications:
      • Results order: Results returned in reverse chronological order
      • Ability to exclude replies (user Tweet timeline only)
      • Ability to exclude Retweets (user Tweet timeline only)
  • Differences
    • New Authentication capability: 
      • OAuth 2.0 Bearer Token (user mention timeline)
    • Access requirements: Twitter API v2 App and Project requirements
    • Rate limits (user mention timeline)
    • Different Request limit & Volume limit
    • Additional pagination method
      • Different max_results (count) per response
    • Request parameters
      • Customized data format based on request parameters, including v2 fields and expansions
      • Additional available data: metrics, Tweet annotations, polls
    • Response format: Twitter API v2 JSON format
       

Similarities

Authentication protocol 

The v1.1 statuses/user_timeline and the Twitter API v2 user Tweet timeline endpoint support both OAuth 1.0a User Context and OAuth 2.0 Bearer Token. Therefore, you can continue using the same authentication method and authorization tokens if you migrate to the Twitter API v2 version. 

Historical Access

The v1.1 statuses/user_timeline and the Twitter API v2 user Tweet timeline endpoint both will return the most recent 3200 Tweets, including Retweets

The v1.1 statuses/mentions_timeline and the Twitter API v2 user mention timeline endpoint can return the most recent 800 Tweets.

Rate Limits

Standard timelines v1.1

timelines v2

user_timeline:

    900 requests per 15 min with OAuth 1.0a User Context

    1500 requests per 15 min with OAuth 2.0 Bearer Token

User Tweets timeline:

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

    1500 requests per 15-minute window with OAuth 2.0 Bearer Token

Refresh polling using since_id

Both versions allow polling for recent results using the since_id.

Traversing timelines by Tweet IDs

Both endpoints have the capability to traverse through timelines using Tweet ID 'timestamps' based on the way Twitter IDs are constructed.  The functionality is generally  the same except for the following:

Standard timelines v1.1

timelines v2

since_id (exclusive)

max_id (inclusive)

since_id (exclusive)

until_id (also exclusive, vs max_id which was inclusive)

Response filtering parameters

Standard timelines v1.1

timelines v2

Response filtering parameters:

  • include_rts
  • exclude_replies

 

Response filtering parameters:

  • exclude=retweets,replies

Example 

https://api.twitter.com/1.1/statuses/user_timeline.json?user_id=2244994945&include_rts=0&&exclude_replies=1

Example:

https://api.twitter.com/2/users/2244994945/tweets?max_results=100&exclude=retweets,replies

Notes:

For user_timeline:

  • Using include_rts=0 does not change the possible historical Tweet limit of the most recent 3200

Notes:

For user Tweets timeline:

  • Using exclude=retweets does not change the possible historical Tweet limit of the most recent  3200 
  • Using exclude=replies reduces the possible historical Tweet limit to the most recent 800 replies

Differences

Authorization access

The v1.1 statuses/mentions_timeline endpoint only supports  OAuth 1.0a User Context.  The Twitter API v2 user mention timeline endpoint supports both OAuth 1.0a User Context and OAuth 2.0 Bearer Token

If you would like to take advantage of the ability to access private or promoted metrics using the Twitter API v2 user Tweet timeline endpoint, you will need to use OAuth 1.0a User Context, and pass the user access tokens related to the user who posted the Tweet for which you would like to access metrics.

Endpoint URLs

Note that the Twitter API v2 timelines endpoints require a path parameter of :id for the user ID.

  • Standard v1.1 endpoints:
    • https://api.twitter.com/1.1/statuses/user_timeline
    • https://api.twitter.com/1.1/statuses/mention_timeline
  • Twitter API v2 endpoint:
    • https://api.twitter.com/2/users/:id/tweets
    • https://api.twitter.com/2/users/:id/mentions


App and Project requirements

The Twitter API v2 endpoints require that you use credentials from a developer App that is associated to a Project when authenticating your requests. All Twitter API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a project. 

Rate Limits

mentions_timeline:

75 requests per 15 min with OAuth 1.0a User Context

user mention timeline: 

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

    450 requests per 15-minute window with OAuth 2.0 Bearer Token



Request limits

Standard timelines v1.1

timelines v2

Daily request limit

  • 100,000 request cap within a 24 hour period.

No daily request limits, only limited by consumption volume.

Consumption volume limits

Standard timelines v1.1

timelines v2

Consumption limited only by request limits

  • 100,000 request cap within a 24 hour period.

Consumption limited by only Project level monthly volume limit (across multiple v2 endpoints)

  • 500,000 Tweet volume cap per Project within a monthly period.
 

Request parameters

Standard timelines v1.1

timelines v2

Required: user_id or screen_name
Required: The specific user ID is specified in the path parameter

Optional:

count - sets the maximum results returned per request

exclude_replies - removes replies from the results

Include_rts - when set to 0 removes retweets from the results

trim_user - removes rehydrated user objects from the results

tweet_mode - sets the data format returned for the results, set to extended for Tweets longer than 140

since_id - sets the earliest Tweet ID in result (exclusive)

max_id - sets the latest Tweet ID in result (inclusive)

Optional:

max_results - sets the maximum results returned per request

exclude=retweets,replies - removes Retweets or replies from the results

tweet.fields - sets the Tweet object fields to return

user.fields - sets the User object fields to return

place.fields - sets the place object fields to return

media.fields - sets the media object fields to return

poll.fields - sets the poll object fields to return

expansions - sets the expanded fields and data to return

start_time - sets the earliest created_at time for the results

end_time - sets the latest created_at time for the results

since_id - sets the earliest Tweet ID for the  results (exclusive)

until_id - sets the latest Tweet ID in result (exclusive)

Request format

Standard timelines v1.1

timelines v2

curl --request GET \
  --url 'https://api.twitter.com/1.1/statuses/user_timeline.json?user_id=2244994945&count=200&include_rts=1&tweet_mode=extended' \
  --header 'Authorization: Bearer XXXXX'
curl --request GET \
  --url 'https://api.twitter.com/2/users/2244994945/tweets?tweet.fields=attachments,author_id,created_at,entities,geo,id,in_reply_to_user_id,lang,possibly_sensitive,public_metrics,referenced_tweets,source,withheld&user.fields=created_at,description,entities,id,location,name,profile_image_url,protected,public_metrics,url,username,verified,withheld&expansions=author_id,referenced_tweets.id,referenced_tweets.id.author_id,entities.mentions.username,attachments.media_keys&media.fields=duration_ms,height,preview_image_url,public_metrics,url,width&max_results=100' \
  --header 'Authorization: Bearer XXXXX'
curl --request GET \
  --url 'https://api.twitter.com/1.1/statuses/mentions_timeline.json?count=200' \
  --header 'Authorization: OAuth oauth_consumer_key="XXXXX", oauth_nonce="XXXXX", oauth_signature="XXXXX", oauth_signature_method="HMAC-SHA1", oauth_timestamp="XXXXX", oauth_token="XXXXX", oauth_version="1.0"'
 curl --request GET \ --url 'https://api.twitter.com/2/users/2244994945/mentions?tweet.fields=attachments%2Cauthor_id%2Ccreated_at%2Centities%2Cgeo%2Cid%2Cin_reply_to_user_id%2Clang%2Cpossibly_sensitive%2Cpublic_metrics%2Creferenced_tweets%2Csource%2Cwithheld&user.fields=created_at%2Cdescription%2Centities%2Cid%2Clocation%2Cname%2Cprofile_image_url%2Cprotected%2Cpublic_metrics%2Curl%2Cusername%2Cverified%2Cwithheld&expansions=author_id%2Creferenced_tweets.id%2Creferenced_tweets.id.author_id%2Centities.mentions.username%2Cattachments.media_keys&media.fields=duration_ms%2Cheight%2Cpreview_image_url%2Cpublic_metrics%2Curl%2Cwidth&max_results=100' \ --header 'Authorization: Bearer XXXXX'

 

Response format

Standard search v1.1

Search Tweets v2

  [
    {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"
  }
}

 

Twitter API v2 JSON format

Twitter API v2 is introducing new JSON designs for the objects returned by the APIs, including Tweet and user objects. You can learn more about the Twitter API v2 format, how to use fields and expansions by visiting our guide, and by reading through our broader data dictionary

  • At the JSON root level, the standard endpoints return Tweet objects in a statuses array, while Twitter API v2 returns a data array. 
  • Instead of referring to Retweeted and Quoted "statuses", Twitter API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. 
  • Instead of using both favorites (in Tweet object) and favourites (in user object), Twitter API v2 uses the term like. 
  • Twitter is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Tweet and user attributes are only included if they have a non-null values.

One of the biggest differences between standard v1.1 and Twitter API v2 endpoint versions is how you select which fields return in your payload. For the standard endpoints, there are several parameters that you could use to identify which fields or sets of fields would return in the payload, while the Twitter API v2 version simplifies these different parameters into fields and expansions

  • fields: Twitter API v2 endpoints enable you to select which fields are provided in your payload. For example, Tweet, user, Media, Place, and Poll objects all have a list of fields that can be returned (or not). 
  • expansions: Used to expand the complementary objects referenced in Tweet JSON payloads. For example, all Retweets and Replies reference other Tweets. By setting expansions=referenced_tweets.id, these other Tweet objects are expanded according to the tweet.fields setting.  Other objects such as users, polls, and media can be expanded. 
  • conversation_id
  • Two new annotations fields, including context and entities
  • Several new metrics fields 


Next steps

Check out our quick start guide for Twitter API v2 timelines

Review the API reference

Check out some sample code for these endpoints

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.