Integration guide

This page contains information on several tools and key concepts that you should be aware of as you integrate the Posts lookup endpoints into your system. We’ve broken the page into a couple of different sections:

• Helpful tools
• Key Concepts
  • Authentication
  • Developer portal, Projects, and Apps
  • Rate limits
  • Fields and expansions
  • Post edits
  • Edge cases

Helpful tools

Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with the following:

Postman

Postman is a great tool that you can use to test out an endpoint. 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 getting started with Postman guide.

Code samples

Interested in getting set up with this endpoint 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.

Third-party 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.
 

Key concepts

Authentication

All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, OAuth 2.0 App-Only, or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to these endpoints. 

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.

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.

Developer portal, Projects, and developer Apps

To retrieve a set of authentication credentials that will work with the X 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. You can then find your keys and tokens within your developer App. 

Rate limits

Everyday, many thousands of developers make requests to the X API, and in order to manage the sheer volume of these requests, rate limits are placed on each endpoint. Rate limits number the requests that you can make on behalf of your app or on behalf of an authenticated user. 

This endpoint is rate limited at both the App-level and the user-level. The app rate limit means that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by using either the API Key and API Secret Key, or the App Access Token). The user rate limit means that the authenticated user that you are making the request on behalf of can only perform a Posts lookup a certain number of times across any developer App.

Fields and expansions

The X API v2 allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. The expansion parameter allows you to expand objects referenced in the payload. For example, this endpoint allows you to pull the following expansions:

• edit_history_tweet_ids
• attachments.poll_ids
• attachments.media_keys
• author_id
• entities.mentions.username
• geo.place_id
• in_reply_to_user_id
• referenced_tweets.id
• referenced_tweets.id.author_id
  

The fields parameter allows you to select exactly which fields within the different data objects you would like to receive. These endpoints deliver Post objects primarily. By default, the Post object returns the id,  text, and edit_history_tweet_ids fields. To receive additional fields such as tweet.created_at or tweet.entities, you will have to specifically request those using a fields parameter. When you include edit_controls, you will receive information about whether the Post was ever eligible for edits, a timestamp indicating whether the 30-minute edit period has ended, and how many edit opportunities remain. Other important fields that you may want to consider using in your integration are our poll data, metrics, Post annotations, and conversation ID fields.

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

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 Post lookup endpoint 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. To learn more about how Post edits work, see the Edit Posts fundamentals page.  

Edge cases

• 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.
• Post text is truncated for Retweets. 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.