Tweets lookup

​

Introduction

The Post is one of the primary resources on X. In its simplest form, a Post can contain up to 280 characters and can be posted either publicly or privately, depending on an account’s settings. However, a variety of different objects can also be attached to Post, including media, a place, polls, and URLs. In addition, most Posts can be edited for up to 30 minutes after being created.

While there are a variety of HTTP, selection, and delivery methods for Posts, this group of REST endpoints focuses on returning a Post or group of Posts, specified by a Post ID. These endpoints can receive up-to-date details on a Post, verify that a Post is available, and examine its edit history. They are also crucial for managing compliance events.

The Post lookup endpoint provides edited Post metadata. All Posts created since September 29, 2022, include edit metadata, even if they were never edited. Each edit results in a new Post ID, with a Post’s edit history represented by an array of Post IDs, beginning with the original.

This endpoint will always return the most recent edit along with its edit history. Any Post collected after its 30-minute edit window has expired will represent its final version. To learn more about Edit Post metadata, check out the Edit Posts fundamentals page.

These endpoints use the GET HTTP method and return one or many Posts objects, which include fields such as the Post text, creation timestamp, and lists and metadata of hashtags, mentions, and photos.

​

Quick Links

​

Getting started with the Posts lookup endpoints

This quick start guide will help you make your first request to the Posts lookup endpoints with a set of specified fields using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository.

​

Steps to build a GET /tweets request

​

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, click the button below:

Once you have the X API v2 collection loaded in Postman, navigate to the “Post Lookup > Multiple Posts” request.

​

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. You can authenticate your request with:

• OAuth 2.0 App-Only
• OAuth 2.0 Authorization Code with PKCE
• OAuth 1.0a User Context

For simplicity’s sake, we are going to utilize OAuth 2.0 App-Only with this request, but if you’d like to request private metrics or Posts, you will need to use one of the other authentication methods.

To utilize OAuth 2.0 App-Only, you must add your keys and tokens (and specifically the App Access Token, also known as the App-only Bearer Token) to Postman by selecting the environment named “X API v2” (in the top-right corner of Postman), and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

If you’ve done this correctly, these variables will automatically be pulled into the request’s authorization tab.

​

Step three: Identify and specify which Posts you would like to retrieve

You must specify a Post or a set of Posts that you would like to receive within the request. You can find the Post ID by navigating to X.com and clicking on a Post and then looking in the URL. For example, the following URL’s Post ID is 1228393702244134912.

https://twitter.com/TwitterDev/status/1228393702244134912

In Postman, navigate to the “Params” tab and enter this ID, or a string of Post IDs separated by a comma, into the “Value” column of the ids parameter.

​

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default Post object fields in your response: id, text, and edit_history_tweet_ids.

For this exercise, we will request a three additional different sets of fields from different objects:

• The additional tweet.created_at field in the primary user objects.
• The associated authors’ user object’s default fields for the returned Posts: id, name, and username
• The additional user.created_at field in the associated user objects.

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should see this URL next to the “Send” button:

https://api.x.com/2/tweets?ids=1228393702244134912,1227640996038684673,1199786642791452673&tweet.fields=created_at&expansions=author_id&user.fields=created_at

​

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive the following response:

{
    "data": [
        {
            "edit_history_tweet_ids": [
                "1228393702244134912"
            ],
            "text": "What did the developer write in their Valentine’s card?\n  \nwhile(true) {\n    I = Love(You);  \n}",
            "id": "1228393702244134912",
            "created_at": "2020-02-14T19:00:55.000Z",
            "author_id": "2244994945"
        },
        {
            "edit_history_tweet_ids": [
                "1227640996038684673"
            ],
            "text": "Doctors: Googling stuff online does not make you a doctor\n\nDevelopers: https://t.co/mrju5ypPkb",
            "id": "1227640996038684673",
            "created_at": "2020-02-12T17:09:56.000Z",
            "author_id": "2244994945"
        },
        {
            "edit_history_tweet_ids": [
                "1199786642791452673"
            ],
            "text": "C#",
            "id": "1199786642791452673",
            "created_at": "2019-11-27T20:26:41.000Z",
            "author_id": "2244994945"
        }
    ],
    "includes": {
        "users": [
            {
                "name": "Developers",
                "created_at": "2013-12-14T04:35:55.000Z",
                "id": "2244994945",
                "username": "XDevelopers"
            }
        ]
    }
}

​

Tweets Lookup - Integration Guide

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
• 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, 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 User Context using API Keys, Access Tokens, and additional parameters to create an authorization header.
• OAuth 2.0 App-Only by passing an App Access Token with your request.
• OAuth 2.0 Authorization Code with PKCE for greater control over app scope and multi-device authorization.

​

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

​

Tweets Lookup - Comparison and Migration

​

Comparing X API’s Posts Lookup Endpoints

The v2 Posts lookup endpoints replace the standard v1.1 GET statuses/lookup and GET statuses/show endpoints, as well as the Labs Post lookup endpoints. This guide is for developers migrating from these older versions to X API v2.

​

Endpoint Comparison Table

​

Standard v1.1 compared to X API v2

If you have been working with the standard v1.1 GET statuses/show and GET statuses/lookup, this guide will help you understand the similarities and differences between the standard and X API v2 Posts lookup endpoints.

You may also be interested in our visual data format migration tool to help you quickly see the differences between the X API v1.1 data format and the X API v2 format.

• Similarities

  • OAuth 1.0a User Context
  • Posts per request limits
  • Support for Post edit history and metadata

• Differences

  • Endpoint URLs
  • App and Project requirements
  • Response data format
  • Request parameters

​

Similarities

​

OAuth 1.0a User Context Authentication Method

The standard endpoint supports OAuth 1.0a User Context, while the new X API v2 Post lookup endpoint supports both OAuth 1.0a User Context and OAuth 2.0 App-Only. Therefore, if you were previously using one of the standard v1.1 Post lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.

App-Only authentication is likely the easiest way to get started. To learn how to generate an App Access Token, see this OAuth 2.0 App-only guide.

​

Posts per Request Limits

The v1.1 GET statuses/lookup endpoint allows you to specify up to 100 Posts per request. This also applies to the GET /tweets endpoint. To specify a full 100 Posts, use the ids parameter as a query parameter with a comma-separated list of Post IDs.

Support for Post Edit History and Metadata

Both versions provide metadata that describes any edit history. Check out the Post lookup API References and the Edit Posts fundamentals page for more details.

​

Differences

​

Endpoint URLs

• Standard v1.1 endpoints:

  • https://api.x.com/1.1/statuses/show
  • https://api.x.com/1.1/statuses/lookup

• X API v2 endpoint:

  • https://api.x.com/2/tweets
  • https://api.x.com/2/tweets/:id

​

App and Project Requirements

X API v2 endpoints require credentials from a developer App associated with a Project for authentication. X API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a Project.

​

Response Data Format

A significant difference between standard v1.1 and X API v2 endpoint versions is how fields are selected in the payload.

For standard endpoints, many response fields are included by default, with options to use parameters to specify additional fields.

X API v2, however, only delivers the Post id and text fields by default. Additional fields and objects require the use of fields and expansions parameters. The expanded fields return in an includes object within the response, which can be matched to the primary Post object by matching IDs.

For more on using fields and expansions, see the guide on how to use fields and expansions. A data format migration guide also maps standard v1.1 fields to the newer v2 fields.

Additionally, X API v2 introduces new JSON designs for objects, including the Post and user objects:

• Standard endpoints return Post objects in a statuses array, while X API v2 uses a data array.
• Retweeted and Quoted Tweets in X API v2 replace “statuses” terminology.
• New terminology such as like replaces terms like favorites and favourites.
• Attributes with no values (e.g., null) are not included in X API v2 payloads.

The Post object in X API v2 includes new fields such as:

• conversation_id
• Two new annotations fields (context and entities)
• New metrics fields
• reply_setting field showing who can reply to a given Post

​

Request Parameters

The following standard v1.1 request parameters have equivalents in X API v2:

Certain standard v1.1 parameters are not supported in X API v2:

​

CURL Requests

The following cURL requests show standard v1.1 endpoints and their v2 equivalents. Replace ACCESS_TOKEN in the header with your app access token. For v2 endpoints, the token must belong to a developer App within a Project.

The response payloads from v1.1 will differ from v2. With v2, you can request different fields with the fields and expansions parameters.

Standard v1.1 GET statuses/lookup and v2 GET /tweets endpoints

curl --request GET \
  --url 'https://api.x.com/1.1/statuses/lookup.json?id=1460323737035677698%2C1460323743339741184' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

curl --request GET \
--url 'https://api.x.com/2/tweets?ids=1460323737035677698%2C1460323743339741184&tweet.fields=created_at&expansions=author_id&user.fields=created_at' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Standard v1.1 GET statuses/show/:id and v2 GET /tweets/:id endpoints

curl --request GET \
  --url 'https://api.x.com/1.1/statuses/show.json?id=1460323737035677698' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

curl --request GET \
  --url 'https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at&expansions=author_id&user.fields=created_at' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

​

API reference index

For the complete API reference, select an endpoint from the list:

​

GET /2/tweets

Returns a variety of information about the Tweet specified by the requested ID or list of IDs.

Run in Postman ❯

Try a live request ❯

Build request with API Explorer ❯

​

Endpoint URL

https://api.x.com/2/tweets

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const lookupTweetsById = await twitterClient.tweets.findTweetsById({
      //A comma separated list of Tweet IDs. Up to 100 are allowed in a single request
      ids: [
        "1460323737035677698",
        "1519781379172495360",
        "1519781381693353984",
      ],
    });
    console.dir(lookupTweetsById, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

• Default fields
• Optional fields

{
  "data": [
    {
      "id": "1460323737035677698",
      "text": "Introducing a new era for the Twitter Developer Platform! nn📣The Twitter API v2 is now the primary API and full of new featuresn⏱Immediate access for most use cases, or apply to get more access for freen📖Removed certain restrictions in the Policynhttps://t.co/Hrm15bkBWJ https://t.co/YFfCDErHsg",
      "edit_history_tweet_ids": [
        "1460323737035677698"
      ]
    },
    {
      "id": "1519781379172495360",
      "text": "Our mission remains just as important as ever: to deliver an open platform that serves the public conversation. We're continuing to innovate on the Twitter API v2 and invest in our developer community 🧵nnhttps://t.co/Rug1l46sUc",
      "edit_history_tweet_ids": [
        "1519781379172495360"
      ]
    },
    {
      "id": "1519781381693353984",
      "text": "Catch up on recent launches and build with the core elements of the Twitter experience:n🔖 New Bookmarks endpointsn💬 New Quote Tweets lookup endpointsn🔼 New sort_order parameter on search endpoints, and improvements to the Likes and Retweets endpoints",
      "edit_history_tweet_ids": [
        "1519781381693353984"
      ]
    }
  ]
}

​

Response fields

​

GET /2/tweets/:id

Returns a variety of information about a single Tweet specified by the requested ID.

Try a live request ❯

Build request with API Explorer ❯

​

Endpoint URL

https://api.x.com/2/tweets/:id

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const lookupTweetById = await twitterClient.tweets.findTweetById(
      //The ID of the Tweet
      "1460323737035677698"
    );
    console.dir(lookupTweetById, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

• Default fields
• Optional fields

{
  "data": {
    "id": "1460323737035677698",
    "text": "Introducing a new era for the Twitter Developer Platform! nn📣The Twitter API v2 is now the primary API and full of new featuresn⏱Immediate access for most use cases, or apply to get more access for freen📖Removed certain restrictions in the Policynhttps://t.co/Hrm15bkBWJ https://t.co/YFfCDErHsg",
    "edit_history_tweet_ids": [
      "1460323737035677698"
    ]
  }
}

​

Response fields