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 broken the page into the following sections:

 

Helpful tools

Before we dive into some key concepts, we recommend that you explore these endpoints using one of the following tools or code examples.

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 communities’ 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 Twitter API v2 endpoints require requests to be authenticated with a set of credentials, also known as keys and tokens. You can use either OAuth 2.0 Bearer Token or OAuth 1.0a User Context to authenticate requests to these endpoints. 

OAuth 2.0 Bearer Token just requires that you pass a Bearer Token with your request. You can either generate a Bearer Token from directly within a developer App, or generate one using the POST oauth2/token endpoint.

OAuth 1.0a User Context is a method that requires a set of API keys and user access tokens to make a successful 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 or authenticate your App using the 3-legged OAuth flow.

Note that OAuth 1.0a can be tricky to use. If you are not familiar with this authentication method, we recommend that you use a library to properly authenticate your requests.

Please note

If you are requesting the following fields, OAuth 1.0a User Context is required: 

  • 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

Developer portal, Projects, and developer Apps

To work with any Twitter API v2 endpoints, you must have an approved 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 Twitter API. To help manage the sheer volume of these requests, rate limits are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. 

There are different rate limits applied for these endpoints depending on which authentication you are using.  The app-level rate limits apply to your application making requests, whereas the user-level rate limit applies to requests being made on behalf of the specific authorizing user.  These two rate limits are based on the frequency of requests within a 15 minute window.

For example, an app using OAuth 2.0 Bearer Token auth for both of these timelines endpoints, can make 1500 requests (including pagination requests) to the user Tweet 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 Tweet timeline, and 180 requests (including pagination requests) to the user mention timeline for each authorized user. 

 

Latency of polling for new Tweets

User Tweets timeline and user mention timeline endpoints will show newly created Tweets about 10 seconds after they are created. 

For example, a Tweet created at 2021-01-04T17:09:04.000Z will be available to retrieve in user Tweets timeline and user mention timeline at 2021-01-04T17:09:14.000Z. 

This is by design for performance, and for consistency across the Twitter API v2.  This latency allows time to populate extra metadata that takes time to process additional metrics and information about shared links.  This latency may be noticed more if you are using these endpoints to poll for retrieving new Tweets, or making requests without an end_time or until_id which would default to a 'now' default end_time.  Please let us know if your use case requires lower latency for this endpoint, or if there is a different delivery format desired for receiving this type of information, such as a streaming or webhook delivery.

 

Fields and expansions

The Twitter 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 Tweet 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, Tweet annotations, and conversation ID fields.

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

Tweet metrics

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

There are some limitations with Tweet 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 Tweet’s publisher to retrieve this data on their behalf when using the user Tweet timeline endpoint, meaning you must use OAuth 1.0a User Context.

For example, in order to receive non_public_metrics for user ID 1234's user Tweet 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 Tweets created in the last 30 days. This means that when you are requesting the noted fields, the results will automatically adjust to only include Tweets from the last 30 days.

If these noted fields are requested, only Tweets that are authored by the authenticated user will be returned, all other Tweets 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 Tweets 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 Tweet IDs to select a specific set of Tweets, you can use the since_id and until_id. The user Tweets timeline also has an exclude parameter that can remove Retweets and Replies from your results. 

Tweet caps and volume of Tweets returned

The user Tweet timeline and user mention timeline endpoints are limited in the number of Tweets that they can return you, regardless of pagination. 

Regardless of which timelines endpoint you use, the Tweets returned will count towards the Project limit of 500,000 Tweets per month. Usage is shown in the developer portal, and the 'month' starts on your subscription renewal day shown on the developer portal dashboard

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

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

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

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.