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
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
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