This page contains information on several tools and key concepts to help you integrate the Posts lookup endpoints into your system. We’ve organized the page into a few sections:

​
Helpful tools

Before we dive into some key concepts, we recommend familiarizing yourself with the following tools:

Postman
Postman is an excellent tool to test out an endpoint, including every path and body parameter to help you understand what’s available. Check out our getting started with Postman guide to learn more.

Code samples
Find code samples for your preferred programming language on our Github page.

Third-party libraries
Utilize community-built third-party libraries compatible with v2 endpoints.

​
Key Concepts

​
Authentication

All X API v2 endpoints require authenticated requests. You can authenticate with either:

OAuth 1.0a can be challenging to implement. If unfamiliar, consider using a library or OAuth 2.0 for requests. For private metrics or Posts, use OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE.

Please note

If you are requesting the following fields, OAuth 1.0a User Context or OAuth 2.0 Authorization Code 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 Apps

To obtain credentials for X API v2, you need:

  1. An approved developer account.
  2. A Project within the developer account.
  3. A developer App within that Project, where keys and tokens can be found.

​
Rate limits

X API requests are subject to rate limits to manage volume. Limits apply at both the App and user levels:

  • App-level: Limits the number of requests made per period by any app.
  • User-level: Limits how frequently an authenticated user can perform Post lookups across developer Apps.

​
Fields and expansions

The X API v2 allows selection of specific data fields using fields and expansions:

  • Expansions: Enable retrieval of additional related objects. Supported expansions include:

    • 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

  • Fields: Specify data fields within objects to return additional data. The Post object defaults to id, text, and edit_history_tweet_ids. Other options, like tweet.created_at and tweet.entities, must be explicitly requested.

For more, refer to the fields and expansions guide in the X API v2 data dictionary.

​
Post edits

Eligible Posts can be edited up to five times within 30 minutes of publishing. The Posts lookup endpoint always provides the latest Post version. For near-real-time use cases, be aware of this time window. For more details, see Edit Posts fundamentals.

​
Edge cases

  • Promoted metrics: Requesting promoted metrics for non-promoted Posts returns an empty response.
  • Truncated text: Post text is truncated for Retweets. To retrieve full text, expand the referenced Post
QuickstartPost lookup by Post IDs