Timelines

​

Introduction

These three timelines endpoints support edited Posts. These endpoints will always return the most recent edit, along with the edit history. Any Post collected after its 30-minute edit window will represent its final version. Edit metadata includes an array of IDs for all Posts in its history. For Posts with no edit history, this array will hold a single ID. For Posts that have been edited, this array contains multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. To learn more about how Post edits work, see the Edit Posts fundamentals page.

​

Reverse chronological home timeline

This endpoint enables you to retrieve the most recent Posts, Retweets, and replies posted by the authenticated user and the accounts they follow. 

Since you are making requests on behalf of a user, you must authenticate these endpoints using an OAuth 2.0 Authorization Code Flow with PKCE or OAuth 1.0a User Context. This endpoint has a per-user rate limit of 180 requests per 15-minute window. This endpoint can return every Post created on a timeline over the last 7 days as well as the most recent 800 regardless of creation date.

​

User Post timeline

The user Post timeline endpoint provides access to Posts published by a specific X account.  Retrieving a user’s Posts allows you to build experiences such as showcasing a timeline in a user interface, analyzing a user’s Posts to better understand their content, or creating engagement workflows with their Posts programmatically. This endpoint gives you access to a single X account’s most recent Posts, Retweets, replies, and Quote Tweets, similar to what may be seen on a user’s profile timeline.

Here is a user timeline for @XDevelopers:

The user Post timeline endpoint is a REST endpoint that receives a single path parameter to indicate the desired user (by user ID). The endpoint can return the 3,200 most recent Posts, Retweets, replies, and Quote Tweets posted by the user.

Posts are delivered in reverse-chronological order, starting with the most recent. Results are paginated up to 100 Posts per page. Pagination tokens are provided for paging through large sets of Posts. The Post IDs of the newest and the oldest Posts included in the given page are also provided as metadata, which can also be used for polling timelines for recent Posts. The user Post timeline also supports the ability to specify start_time and end_time parameters to receive Posts that were created within a certain window of time. 

The user Post timeline endpoint supports fields and expansions parameters, and returns the new JSON data format.

To successfully make a request to this endpoint, you will need to authorize your request with the OAuth 1.0a User Context, OAuth 2.0 Authorization Code with PKCE, or [OAuth 2.0 App-Only](https://developer.twitter.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token) authentication methods. You must use OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE when requesting nonpublic metrics, promoted metrics or a protected user’s timeline. 

The user Post timeline endpoint is designed to support two common usage patterns: 

• “Get a user’s historical Posts”: Requests made to user Post timeline in order to receive Posts authored by the user of interest in chronological order over a specific recent timeframe. The timeframe can be set using the start_time and end_time and paginating through the full results.  In some cases, a user’s entire history of Posts can be retrieved if the user has only authored up to 3,200 Posts in their account. Posts included will depend on the public availability and the authentication that is used for the requests.

• ”Polling for new Posts”: Requests made to user Post timeline on a continual basis, to retrieve new Posts authored by a specific user. The last Post ID received can be set as a parameter for any new requests since the last Post.

​

User mention timeline

The user mention timeline endpoint allows you to request Posts mentioning a specific X user, for example, if a X account mentioned @XDevelopers within a Post. This will also include replies to Posts by the user requested. Retrieving a user’s mentions allows you to build experiences such as quickly discovering who is replying to a users’ Posts, mentioning or to create engagement workflows with their Posts programmatically. The endpoint allows you to request to a single user’s most recent mentions and replies, similar to what may be seen in a user’s notifications for mentions on X.

The user mention timeline is a REST endpoint that receives a single path parameter to indicate the desired user (by user ID). The endpoint can return the 800 most recent mentions for that user.

Posts are delivered in reverse-chronological order, starting with the most recent. Results are paginated in up to 100 Posts per page. Pagination tokens are provided for paging through large sets of Posts. The Post IDs of the newest and the oldest Posts included in the given page are also provided as metadata, which can also be used for polling timelines for recent Posts, or for navigating through the timeline similar to the v1.1 mentions_timeline endpoint. The endpoint also supports the ability to specify start_time and end_time parameters to receive Posts that were created within a certain window of time. 

To successfully make a request to this endpoint, you will need to authorize your request with the OAuth 1.0a User Context, OAuth 2.0 Authorization Code with PKCE, or [OAuth 2.0 App-Only](https://developer.twitter.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token) authentication methods. You must use OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE when requesting non public metrics, promoted metrics or a protected user’s timeline. 

The user mention timeline endpoint supports fields and expansions parameters, and returns the new JSON data format.

​

Timelines quick start guide

​

Getting started with reverse chronological home timeline

This quick start guide will help you make your first request to one of the timelines endpoints with a set of specified fields using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

Steps to build a reverse chronological home timeline request

_For this example, we will make a request to the user Post timeline by ID endpoint, but you can apply the learnings from this quick start to user mention timelines requests as well. _

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “Timelines” folder and find the “Reverse chronological home timeline” request.

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do so with this endpoint, you must authenticate your request with either OAuth 2.0 Authorization Code with PKCE, or OAuth 1.0a User Context authentication methods. 

You must add your keys and tokens to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

These variables will automatically be pulled into the request’s authorization tab if you’ve done this correctly.

Step three: Identify and specify which user from which you would like to retrieve their home timeline for

You must specify a user you would like to retrieve recent Posts for within the request. In this example, we will be passing a single user ID.

User IDs are simply the numerical value that represents an account handle that you can find within an account’s profile URL. For example, the following account’s username is XDevelopers.

https://twitter.com/XDevelopers

To convert this username to the user ID, you will have to use the users lookup endpoint with the username and find the numerical user ID in the payload. In the case of @XDevelopers, the user ID is 2244994945.

In Postman, navigate to the “Params” tab and enter this user ID into the “Value” column of the id parameter.

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default Post object fields in your response: id, text, and edit_history_tweet_ids.

If you would like to receive additional fields, you will have to specify those fields in your request with the field and/or expansion parameters.

For this exercise, we will request three additional different sets of fields from different objects:

1. The additional tweet.created_at field in the primary user objects.

2. The associated authors’ user object’s default fields for the returned Posts: id, name, and username

3. The additional user.created_at field in the associated user objects.  

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see the following URL next to the “Send” button:

https://api.x.com/2/users/:id/timelines/reverse_chronological?tweet.fields=created_at&expansions=author_id&user.fields=created_at&max_results=5

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive the following response:

	"data": [
		{
			"created_at": "2022-05-12T17:00:00.000Z",
			"text": "Today marks the launch of Devs in the Details, a technical video series made for developers by developers building with the Twitter API.  🚀\n\nIn this premiere episode, @jessicagarson walks us through how she built @FactualCat #WelcomeToOurTechTalk\n⬇️\n\nhttps://t.co/nGa8JTQVBJ",
			"author_id": "2244994945",
			"id": "1524796546306478083"
		},
		{
			"created_at": "2022-05-11T19:16:40.000Z",
			"text": "📢 Join @jessicagarson @alanbenlee and @i_am_daniele tomorrow, May 12  | 5:30 ET / 2:30pm PT as they discuss the future of bots https://t.co/sQ2bIO1fz6",
			"author_id": "2244994945",
			"id": "1524468552404668416"
		},
		{
			"created_at": "2022-05-09T20:12:01.000Z",
			"text": "Do you make bots with the Twitter API? 🤖\n\nJoin @jessicagarson @alanbenlee and @iamdaniele on Thursday, May 12  | 5:30 ET / 2:30pm PT as they discuss the future of bots and answer any questions you might have. 🎙📆⬇️\n\nhttps://t.co/2uVt7hCcdG",
			"author_id": "2244994945",
			"id": "1523757705436958720"
		},
		{
			"created_at": "2022-05-06T18:19:54.000Z",
			"text": "If you’d like to apply, or would like to nominate someone else for the program, please feel free to fill out the following form:\n\nhttps://t.co/LUuWj24HLu",
			"author_id": "2244994945",
			"id": "1522642324781633536"
		},
		{
			"created_at": "2022-05-06T18:19:53.000Z",
			"text": "We’ve gone into more detail on each Insider in our forum post. \n\nJoin us in congratulating the new additions! 🥳\n\nhttps://t.co/0r5maYEjPJ",
			"author_id": "2244994945",
			"id": "1522642323535847424"
		}
	],
	"includes": {
		"users": [
			{
				"created_at": "2013-12-14T04:35:55.000Z",
				"name": "Twitter Dev",
				"username": "TwitterDev",
				"id": "2244994945"
			}
		]
	},
	"meta": {
		"result_count": 5,
		"newest_id": "1524796546306478083",
		"oldest_id": "1522642323535847424",
		"next_token": "7140dibdnow9c7btw421dyz6jism75z99gyxd8egarsc4"
	}
}

Step six: Paginate through your results

In the previous response, you will find a meta data object at the bottom that includes the following fields:

• oldest_id
• newest_id
• results_count
• next_token
• previous_token

In step four, we passed a max_results value of 5, meaning that each page will only include up to five results. To access the additional pages of data, we will be taking the value of the next_token field from our last results and adding that string as the value of the pagination_token parameter on the Postman params page, keeping everything else constant. 

Once this is all set up, you can click “Send” again and you should receive the next page of results. 

We have put together a guide on pagination to further explain this concept. 

​

Getting started with the user Post and mention timeline endpoints

This quick start guide will help you make your first request to the user Post timeline endpoint with a set of specified fields using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

Steps to build a timelines request

_For this example, we will make a request to the user Post timeline by ID endpoint, but you can apply the learnings from this quick start to user mention timelines requests as well. _

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the timeline folder and find the “User Post timeline by ID” request.  

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do so with this endpoint, you must authenticate your request with either OAuth 2.0 App-Only, OAuth 2.0 Authorization Code with PKCE, or OAuth 1.0a User Context authentication methods.

For simplicity’s sake, we will utilize OAuth 2.0 App-Only with this request, but you will need to use one of the other authentication methods if you’d like to request private metrics or Posts. 

You must add your keys and tokens, specifically the App Access Token (also known as the App-only Bearer Token) to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

This variable will automatically be pulled into the request’s authorization tab if you’ve done this correctly.  

Step three: Identify and specify which user from which you would like to retrieve Posts

You must specify a user you would like to retrieve recent Posts for within the request. In this example, we will be passing a single user ID.

User IDs are simply the numerical value that represents an account handle that you can find within an account’s profile URL. For example, the following account’s username is XDevelopers.

https://twitter.com/XDevelopers

To convert this username to the user ID, you will have to use the users lookup endpoint with the username and find the numerical user ID in the payload. In the case of @XDevelopers, the user ID is 2244994945.

In Postman, navigate to the “Params” tab and enter this user ID into the “Value” column of the id parameter.

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default Post object fields in your response: id and text.

If you would like to receive additional fields beyond id and text, you will have to specify those fields in your request with the field and/or expansion parameters.

For this exercise, we will request a three additional different sets of fields from different objects:

1. The additional tweet.created_at field in the primary user objects.

2. The associated authors’ user object’s default fields for the returned Posts: id, name, and username

3. The additional  user.created_at field in the associated user objects.  

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see the following URL next to the “Send” button:

https://api.x.com/2/users/:id/tweets?tweet.fields=created_at&expansions=author_id&user.fields=created_at&max_results=5

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive the following response:

    "data": [
        {
            "author_id": "2244994945",
            "created_at": "2020-09-03T17:31:39.000Z",
            "id": "1301573587187331074",
            "text": "Starting today, you can see your monthly Tweet usage for the v2 API in the developer portal. ✨📊\n\nThis tracks how many Tweets you’ve received from filtered stream and recent search. Learn more here: https://t.co/nfJHkFRQcZ https://t.co/vFXmoj3qaA"
        },
        {
            "author_id": "2244994945",
            "created_at": "2020-09-03T15:43:00.000Z",
            "id": "1301546240887398401",
            "text": "RT @snowman: So, we built a live golf leaderboard on the Twitter API with Python, Flask, Postgres, and Heroku.\n\nSend a 'leaderboard' Direct…"
        },
        {
            "author_id": "2244994945",
            "created_at": "2020-09-01T20:07:50.000Z",
            "id": "1300888112948752389",
            "text": "⛳ Why do golfers carry an extra shirt? In case they get a hole in one.\n\nNow that we have your attention, learn how @snowman and @johnd built a real-time golf leaderboard using the #TwitterAPI. 📖\n\nhttps://t.co/rRKeKmaRrN"
        },
        {
            "author_id": "2244994945",
            "created_at": "2020-08-28T23:14:22.000Z",
            "id": "1299485505478963200",
            "text": "RT @jessicagarson: Posted my first tutorial on @ThePracticalDev on using v2 of the Twitter API! You will learn how to explore a user’s Twee…"
        },
        {
            "author_id": "2244994945",
            "created_at": "2020-08-21T19:10:05.000Z",
            "id": "1296887316556980230",
            "text": "See how @PennMedCDH are using Twitter data to understand the COVID-19 health crisis 📊\n\nhttps://t.co/1tdA8uDWes"
        }
    ],
    "includes": {
        "users": [
            {
                "created_at": "2013-12-14T04:35:55.000Z",
                "id": "2244994945",
                "name": "Twitter Dev",
                "username": "TwitterDev"
            }
        ]
    },
    "meta": {
        "newest_id": "1301573587187331074",
        "next_token": "t3buvdr5pujq9g7bggsnf3ep2ha28",
        "oldest_id": "1296887316556980230",
        "previous_token": "t3equkmcd2zffvags2nkj0nhlrn78",
        "result_count": 5
    }
}

​

Step six: Paginate through your results

In the previous response, you will find a meta data object at the bottom that includes the following fields:

• oldest_id
• newest_id
• results_count
• next_token
• previous_token

In step four, we passed a max_results value of 5, meaning that each page will only include up to five results. To access the additional pages of data, we will be taking the value of the next_token field from our last results and adding that string as the value of the pagination_token parameter on the Postman params page, keeping everything else constant. 

Once this is all set up, you can click “Send” again and you should receive the next page of results. 

We have put together a guide on pagination to further explain this concept. 

​

Timelines integration guide

​

How to integrate with the Timelines endpoints

This page contains information on several tools and key concepts that you should be aware of as you integrate the timelines endpoints into your system. We’ve split the page into the following sections:

• Helpful tools
• Key Concepts
  • Authentication
  • Developer portal, Projects, and Apps
  • Rate limits
  • Fields and expansions
  • Post metrics
  • Pagination
  • Filtering results
  • Post caps and volume of Posts returned
  • Edit Posts
  • Edge cases

​

Helpful tools

Before we explore some key concepts, we recommend that you use one of the following tools or code samples to start testing the functionality of these endpoints.

Code samples

Interested in getting set up with these endpoints with some code in your preferred coding language? We’ve got a handful of different code samples available that you can use as a starting point on our GitHub page.

Libraries

Take advantage of one of our many community third-party libraries to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag.

Postman

Postman is a great tool that you can use to test out these endpoints. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our Using Postman page.

​

Key concepts

Authentication

All X API v2 endpoints require requests to be authenticated with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE to authenticate requests to these endpoints. You can use OAuth 2.0 App-Only for user Posts timeline and user mentions timeline.

OAuth 1.0a User Context requires you to utilize your API Keys, user Access Tokens, and a handful of other parameters to create an authorization header, which you will then pass with your request. The Access Tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the 3-legged OAuth flow. 

Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a library, use a tool like Postman, or use OAuth 2.0 to authenticate your requests. If you would like to request a Post or private metrics from these endpoints, you will need to use a either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, which will ensure that you have the proper permissions from the user that owns that content.

OAuth 2.0 App-Only just requires that you pass an OAuth 2.0 App Access Token with your request. You can either generate an App Access Token from directly within a developer App, or generate one using the POST oauth2/token endpoint. You can use this for user Posts timeline or user mention timeline.

OAuth 2.0 Authorization Code with PKCE allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. 

To enable OAuth 2.0 in your App, you must enable it in your’s App’s authentication settings found in the App settings section of the developer portal.

Developer portal, Projects, and developer Apps

To work with any X API v2 endpoints, you must sign up for a developer account, set up a Project within that account, and created a developer App within that Project. Your keys and tokens within that developer App will work for these timelines endpoints.

Rate limits

Every day, many thousands of developers make requests to the X API. To help manage the volume, rate limits are placed on each endpoint that limits the number of requests that every developer can make on behalf of an app or on behalf of an authenticated user. 

There are different rate limits applied for these endpoints depending on which authentication method is being used. The app-level rate limits apply to an App making requests using OAuth 2.0 App-Only, whereas the user-level rate limit applies to requests being made on behalf of the specific authorizing user using OAuth 1.0a User Context. These two rate limits are based on the frequency of requests within a 15-minute window.

For example, an app using OAuth 2.0 App-Only auth for both of these timelines endpoints, can make 1500 requests (including pagination requests) to the user Post timeline, and 450 requests (including pagination requests) to the user mention timeline within a 15-minute timeframe.  That same app, within the same 15-minute timeframe, with two different authorized users (using OAuth 1.0a User Context) can make 900 requests (including pagination requests) to the user Post timeline, and 180 requests (including pagination requests) to the user mention timeline for each authenticated user. 

Reverse chronological home timeline has a per-user rate limit of 180 requests per a 15 min window. With this endpoint you can return every Post created on a timeline over the last 7 days as well as the most recent 800 regardless of creation date.

Fields and expansions

The X API v2 allows you to select exactly which data you want returned from the API using fields and expansions. The expansion parameter allows you to expand objects referenced in the payload. For example, this endpoint allows you to request poll, place, media, and other objects using the expansions parameter.

The fields parameter allows you to select exactly which fields within the different data objects you would like to receive. By default, the primary Post object returned by these endpoints include the id and text fields. To receive additional fields such as author_id or public_metrics, you will have to specifically request those using the fields parameters. Some important fields that you may want to consider using in your integration are our poll data, metrics, Post annotations, and conversation ID fields.

We’ve added a guide on how to use fields and expansions together to our X API v2 data dictionary.

Post metrics

The X API v2 endpoints allow you to request Post metrics directly from the returned Post object, assuming you pass the proper fields with your request.

There are some limitations with Post metrics that you should be aware of, specifically related to user privacy and the following response fields:

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics
• media.fields.non_public_metrics
• media.fields.promoted_metrics
• media.fields.organic_metrics

The noted fields include private metrics data, meaning you must be authorized by the Post’s publisher to retrieve this data on their behalf when using the user Post timeline endpoint, meaning you must use OAuth 1.0a User Context or OAuth 2.0 Authorization Code Flow with PKCE.

For example, in order to receive non_public_metrics for user ID 1234’s user Post timeline you will need to include access tokens associated with that user in your request. You can have users authorize your app and receive a set of access tokens associated with them by using the 3-legged OAuth flow. 

If you are using user mention timeline, the noted fields will not be available unless the mentioning author has authorized your App to access their private metrics data and you are using that user’s access tokens when making the request with OAuth 1.0a User Context.

All non_public_metrics, organic_metrics, and promoted_metrics are only available for Posts created in the last 30 days. This means that when you are requesting the noted fields, the results will automatically adjust to only include Posts from the last 30 days.

If these noted fields are requested, only Posts that are authored by the authenticated user will be returned, all other Posts will receive an error message.

Pagination

These endpoints utilize pagination so that responses are returned quickly. In cases where there are more results than what can be sent in a single response (up to 100 Posts for the timelines endpoints) you will need to paginate. Use the max_results parameter to identify how many results will return per page, and the pagination_token parameter return the next page of results. You can learn more by reviewing our pagination guide.

Filtering results

These endpoints include several parameters that you can use to filter results. Using start_date and end_date, you can narrow down results to a specific timeframe. If you’d rather use POst IDs to select a specific set of Posts, you can use the since_id and until_id. The user Posts timeline also has an exclude parameter that can remove Retweets and Replies from your results. 

Post caps and volume of Posts returned

The user Post timeline and user mention timeline endpoints are limited in the number of Posts that they can return in a given month. The reverse chronological home timeline endpoint is not subject to this limitation.

Regardless of which timelines endpoint you use, the Posts returned will count towards the Project-level Post caps. Usage is shown in the developer portal, and the ‘month’ starts on your subscription renewal day shown on the developer portal dashboard. 

The user Post timeline endpoint will only return the most recent 3200 Posts posted to a user’s timeline. Setting start_time and end_time to a time period that includes Posts beyond the 3200 most recent, you will receive a successful response, but no Posts.

It is also important to note that, if you pass the excludes=replies with your user Post timeline requests, only the most recent 800 Posts will be returned.

The user mention timeline endpoint will only return the most recent 800 Post mentions.

The reverse chronological home timeline endpoint returns the last 3200 Posts.

Post edits

Posts that are eligible for edits can be edited up to five times in the 30 minutes after the original Post was published. The search endpoints will always provide the latest version of the Post. If you only request Posts that were published 30 or more minutes ago, you will always receive the final version of the Post. However, if you have a near-real-time use case, and are querying Posts published within the last thirty minutes, those Posts could have been edited after you received them. These Posts can be rehydrated with search, or the Pos Lookup endpoint to confirm their final state. To learn more about how Post edits work, see the Edit Posts fundamentals page.  

Edge cases

• When requesting non-public metrics on the User Post timeline endpoint for Posts that are older than 30 days, you may see a next_token in the response with a result count of 0. To avoid encountering this issue, ensure that the timeframe requested with the non_public_metrics parameter is within the most recent 30 days. Additionally, the max_results minimum value should be 10. These may help to avoid this scenario, but this could still occur.

• Requesting promoted metrics for Posts that were not promoted returns an empty response, instead of Post data. Our team is currently working on fixing this issue.

• For a Retweet that contains Post body text greater than 140 characters in length, the text field will be truncated instead of returning the full Post text. The short term workaround is to expand the referenced Post and retrieve the full text from the expansion. This is a bug that we will fix in the future.

​

Timelines version comparison

​

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:

​

User Post timeline

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

​

User mention timeline

The following tables compare the standard v1.1 and X API v2 user mention timeline endpoints

Other migration resources

Post lookup: Standard v1.1 to X API v2

X API migration hub

​

Timelines standard v1.1 to v2 migration guide

​

Standard v1.1 timelines to X 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 X API v2 timelines endpoints so that you can migrate your current integration to the new version.

• Similarities:
  • Authentication:
    • OAuth 1.0a User Context (reverse chronological home timeline, user Post timeline and user mentions timeline)
    • OAuth 2.0 App-Only (user Post timeline)
  • Historical Access limit: User timeline (user Post timeline) provides access to most recent 3200 Posts; mentions timeline (user mention timeline) provides access to most recent 800 mentions.
  • Support for Post edit history and metadata
  • Rate limits (user Post timeline)
  • Refresh polling: Ability to retrieve new results since the since_id
  • Traversing timelines by Post IDs
  • Results specifications:
    • Results order: Results returned in reverse chronological order
    • Ability to exclude replies (user Post timeline only)
    • Ability to exclude Retweets (user Post timeline only)
• Differences
  • New Authentication capability: 
    • OAuth 2.0 App-Only (user mention timeline)
    • OAuth 2.0 Authorization Code Flow with PKCE (reverse chronological home timeline, user Post timeline and user mentions timeline)
  • Access requirements: X API v2 App and Project requirements
  • Rate limits (user mention timeline and reverse chronological home timeline)
  • Different Request limit & Volume limit
  • Additional pagination method
    • Different max_results (count) per response
  • Response data format
  • Request parameters
    • Customized data format based on request parameters, including v2 fields and expansions
    • Additional available data: metrics, Post annotations, polls

​

Similarities

Authentication

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

Historical Access

The v1.1 statuses/user_timeline and the X API v2 user Post timeline endpoint both will return the most recent 3200 Posts, including Retweets

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

Support for Post edit history and metadata

Both versions provide metadata that describes any edit history. Check out the filtered stream API References and the Edit Posts fundamentals page for more details. 

Rate Limits

Refresh polling using since_id

Both versions allow polling for recent results using the since_id.  

Traversing timelines by Post IDs

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

Response filtering parameters

​

Differences

Authentication

**The v1.1 statuses/mentions_timeline endpoint only supports OAuth 1.0a User Context.  The X API v2 user mention timeline endpoint supports both OAuth 1.0a User Context,OAuth 2.0 App-Only, and OAuth 2.0 Authorization Code with PKCE **

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

Endpoint URLs

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

• Standard v1.1 endpoints:
  • https://api.x.com/1.1/statuses/home_timeline
  • https://api.x.com/1.1/statuses/user_timeline
  • https://api.x.com/1.1/statuses/mention_timeline
• X API v2 endpoint:
  • https://api.x.com/2/users/:id/timelines/reverse_chronological
  • https://api.x.com/2/users/:id/tweets
  • https://api.x.com/2/users/:id/mentions

App and Project requirements

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

Rate Limits

Request limits

Consumption volume limits

Request parameters

Response data format

X API v2 JSON format

X API v2 is introducing new JSON designs for the objects returned by the APIs, including Post and user objects. You can learn more about the X 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 Post objects in a statuses array, while X API v2 returns a data array. 
• Instead of referring to Retweeted and Quoted “statuses”, X 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 Post object) and favorites (in user object), X API v2 uses the term like. 
• X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null value.  

One of the biggest differences between standard v1.1 and X 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 X API v2 version simplifies these different parameters into fields and expansions. 

• fields: X API v2 endpoints enable you to select which fields are provided in your payload. For example, Post, 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 Post JSON payloads. For example, all Retweets and Replies reference other Posts. By setting expansions=referenced_tweets.id, these other Post 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   

We have put together a data format migration guide which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. 

​

API Reference Index

For the complete API reference, select an endpoint from below.

​

Reverse chronological timeline

​

User Tweet timeline

​

User mention timeline