Introduction

The X API v2 has three timelines endpoints - reverse chronological home timeline, user Post timeline, and user mention timeline. See below for more details.

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:

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