Guides
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
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.Please noteIf you are requesting the following fields, OAuth 1.0a User Context or OAuth 2.0 Authorization Code is required:
tweet.fields.non_public_metricstweet.fields.promoted_metricstweet.fields.organic_metricsmedia.fields.non_public_metricsmedia.fields.promoted_metricsmedia.fields.organic_metrics
tweet.fields.non_public_metricstweet.fields.promoted_metricstweet.fields.organic_metricsmedia.fields.non_public_metricsmedia.fields.promoted_metricsmedia.fields.organic_metrics
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.