> ## Documentation Index > Fetch the complete documentation index at: https://x-preview-mintlify-sse-streaming-1775019876.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # v1 to v2 export const Button = ({href, children}) => { return
; }; ## 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) * 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](/resources/fundamentals/authentication) and [OAuth 2.0 App-Only](/resources/fundamentals/authentication#bearer-token-also-known-as-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](/enterprise-api/posts/filtered-stream/introduction) and the [Edit Posts fundamentals page](/enterprise-api/fundamentals/edit-posts) for more details. **Rate Limits** | | | | :------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Standard v1.1** | **X API v2** | | user\_timeline:

900 requests per 15 min with OAuth 1.0a User Context

1500 requests per 15 min with OAuth 2.0 App-Only | User Posts timeline:

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

1500 requests per 15-minute window with OAuth 2.0 App-Only | **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: | | | | :--------------------------------------------------- | :------------------------------------------------------------------------------------------ | | **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.x.com/1.1/statuses/user\\\_timeline.json?user\\\_id=2244994945\&include\\\_rts=0&\&exclude\\\_replies=1](https://api.x.com/1.1/statuses/user\\_timeline.json?user\\_id=2244994945\&include\\_rts=0&\&exclude\\_replies=1) | Example:

[https://api.x.com/2/users/2244994945/tweets?max\_results=100\&exclude=retweets,replies](https://api.x.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 Post limit of the most recent 3200 | Notes:

For user Posts timeline:

\* Using exclude=retweets does not change the possible historical Post limit of the most recent 3200
\* Using exclude=replies reduces the possible historical Post limit to the most recent 800 replies | ### Differences **Authentication** \*\*The v1.1 statuses/mentions\_timeline endpoint only supports [OAuth 1.0a User Context](https://developer-staging.x.com/resources/fundamentals/authentication). The X API v2 user mention timeline endpoint supports both [OAuth 1.0a User Context](/resources/fundamentals/authentication),[OAuth 2.0 App-Only](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only), and [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authenticationoauth-2-0/authorization-code "This method allows an authorized app to act on behalf of the user, as the user. It is typically used to access or post public information for a specific user, and it us useful when your app needs to be aware of the relationship between a user and what this endpoint returns. Click to learn how to authenticate with 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/home_timeline) * [https://api.x.com/1.1/statuses/user\_timeline](https://api.x.com/1.1/statuses/user_timeline) * [https://api.x.com/1.1/statuses/mention\_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/timelines/reverse_chronological) * [https://api.x.com/2/users/:id/tweets](https://api.x.com/2/users/:id/tweets) * [https://api.x.com/2/users/:id/mentions](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](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from 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 | | **home\_timelime:**

15 requests per 15 minutes

Up to 800 Posts are obtainable on the home timeline | **reverse chronological home timeline:**

180 requests per 15 minutes

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. | **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 Posts longer than 140

since\_id - sets the earliest Post ID in result (exclusive)

max\_id - sets the latest Post 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 Post 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 Post ID for the results (exclusive)

until\_id - sets the latest Post ID in result (exclusive) | **Response data format** | | | | :------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Standard search v1.1** | **Search Posts 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"

| **X API v2 JSON format** X API v2 is introducing new JSON designs for the objects returned by the APIs, including [Post](/enterprise-api/fundamentals/data-dictionary#tweet) and [user](/enterprise-api/fundamentals/data-dictionary#user) objects. You can learn more about the X API v2 format, how to use fields and expansions by visiting our [guide](/enterprise-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions), and by reading through our broader [data dictionary](/enterprise-api/fundamentals/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](/enterprise-api/fundamentals/fields) and [expansions](/enterprise-api/fundamentals/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](/enterprise-api/fundamentals/post-annotations) fields, including context and entities * Several new [metrics](/enterprise-api/fundamentals/metrics) fields We have put together a [data format migration guide](/enterprise-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) 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. *** ## Code examples ### User Posts timeline (v2) ```bash cURL theme={null} curl "https://api.x.com/2/users/2244994945/tweets?max_results=100&tweet.fields=created_at,public_metrics&exclude=retweets,replies" \ -H "Authorization: Bearer $BEARER_TOKEN" ``` ```python Python SDK theme={null} from xdk import Client client = Client(bearer_token="YOUR_BEARER_TOKEN") # Get user's Posts timeline for page in client.posts.get_user_posts( "2244994945", tweet_fields=["created_at", "public_metrics"], exclude=["retweets", "replies"], max_results=100 ): for post in page.data: print(f"{post.created_at}: {post.text[:50]}...") ``` ```javascript JavaScript SDK theme={null} import { Client } from "@xdevplatform/xdk"; const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); // Get user's Posts timeline const paginator = client.posts.getUserPosts("2244994945", { tweetFields: ["created_at", "public_metrics"], exclude: ["retweets", "replies"], maxResults: 100, }); for await (const page of paginator) { page.data?.forEach((post) => { console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`); }); } ``` ### User mentions timeline (v2) ```bash cURL theme={null} curl "https://api.x.com/2/users/2244994945/mentions?max_results=100&tweet.fields=created_at,author_id" \ -H "Authorization: Bearer $BEARER_TOKEN" ``` ```python Python SDK theme={null} from xdk import Client client = Client(bearer_token="YOUR_BEARER_TOKEN") # Get user's mentions for page in client.posts.get_user_mentions( "2244994945", tweet_fields=["created_at", "author_id"], max_results=100 ): for post in page.data: print(f"Mentioned by {post.author_id}: {post.text[:50]}...") ``` ```javascript JavaScript SDK theme={null} import { Client } from "@xdevplatform/xdk"; const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); // Get user's mentions const paginator = client.posts.getUserMentions("2244994945", { tweetFields: ["created_at", "author_id"], maxResults: 100, }); for await (const page of paginator) { page.data?.forEach((post) => { console.log(`Mentioned by ${post.author_id}: ${post.text?.slice(0, 50)}...`); }); } ``` **Next steps** [Check out our quick start guide for X API v2 Post lookup](/enterprise-api/posts/lookup/quickstart "Check out our quick start guide for X API v2 Post lookup") [Review the API references for v2 Post lookup](/enterprise-api/posts/lookup/migrate/overview "Review the API references for v2 Post lookup") [Check out our sample code for the timelines endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out our sample code for the timelines endpoints")