Tweets & Posts

Overview

The Tweets & Posts endpoints provide access to Twitter's core content - tweets. You can retrieve individual tweets by ID, get all replies to a tweet, fetch retweets, and access full conversation threads. All endpoints return rich data including text, media, engagement metrics, and author information.

Key Features

• Tweet Lookup: Get complete tweet data including text, media, metrics, and author
• Replies: Access all replies to any tweet with full conversation context
• Retweets: Retrieve all users who retweeted a specific tweet
• Private Tweets: Access tweets even from private accounts (when authorized)
• Media Support: Full support for images, videos, GIFs, and other media types
• Real-time Data: Get the most up-to-date information available

Authentication

All endpoints require authentication via the X-API-KEY header. Include your API key in every request:

X-API-KEY: YOUR_API_KEY

For more information about authentication, see our Authentication Guide.

Endpoints

Get Tweet by ID

Retrieves a single tweet by its unique ID, including all associated data like media, metrics, author information, and conversation context.

Endpoint: GET /tweet/{tweetId}

Path Parameters

Query Parameters

Request Examples

cURL:

curl --request GET \
  --url 'https://<direct.gateway>/tweet/1668868113725550592?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript (fetch):

const response = await fetch('https://<direct.gateway>/tweet/1668868113725550592?count=20', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'YOUR_API_KEY'
  }
});
 
const data = await response.json();
console.log(data);

Python (requests):

import requests
 
url = "https://<direct.gateway>/tweet/1668868113725550592"
params = {"count": 20}
headers = {"X-API-KEY": "YOUR_API_KEY"}
 
response = requests.get(url, params=params, headers=headers)
data = response.json()
print(data)

Node.js (axios):

const axios = require('axios');
 
const response = await axios.get('https://<direct.gateway>/tweet/1668868113725550592', {
  params: { count: 20 },
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
 
console.log(response.data);

Response Example

The response includes the tweet data along with replies (if any) and pagination cursors:

{
  "data": {
    "threaded_conversation_with_injections_v2": {
      "instructions": [
        {
          "type": "TimelineAddEntries",
          "entries": [
            {
              "entryId": "tweet-1668868113725550592",
              "content": {
                "itemContent": {
                  "tweet_results": {
                    "result": {
                      "__typename": "Tweet",
                      "rest_id": "1668868113725550592",
                      "core": {
                        "user_results": {
                          "result": {
                            "rest_id": "44196397",
                            "legacy": {
                              "screen_name": "elonmusk",
                              "name": "Elon Musk",
                              "followers_count": 226943745,
                              "verified": false
                            }
                          }
                        }
                      },
                      "legacy": {
                        "full_text": "This is the tweet text content",
                        "created_at": "Wed Jun 14 12:00:00 +0000 2023",
                        "favorite_count": 5234,
                        "retweet_count": 1234,
                        "reply_count": 567
                      },
                      "views": {
                        "count": "59242758"
                      },
                      "edit_control": {
                        "is_edit_eligible": true,
                        "edits_remaining": "5"
                      }
                    }
                  }
                }
              }
            }
          ]
        }
      ]
    }
  },
  "cursor": {
    "top": "DAABCgABGNqxkNkKAAIZ2rGBvwoAABnatQ7dCgACGdq1DQ8IAAIZ2rqXFQgAAhnauprOAAA",
    "bottom": "DAABCgABGNqxkNkKAAIZ2rqXFQgAAhnauprOAAA"
  }
}

Response Fields

Common Use Cases

1. Display a single tweet: Use this endpoint to show tweet details in your application
2. Get tweet metrics: Access engagement data (likes, retweets, views)
3. Fetch conversation context: Retrieve replies along with the original tweet
4. Media extraction: Access images, videos, and other media attached to the tweet

Notes

• The count parameter controls how many replies are included in the response
• Use the cursor parameter for pagination through replies
• Tweet IDs are unique and never change, even if the tweet is edited
• Deleted tweets will return a 404 error

Get Tweet Retweets

Retrieves all users who retweeted a specific tweet. This is useful for understanding tweet reach and identifying influential retweeters.

Endpoint: GET /tweet/{tweetId}/retweets

Path Parameters

Query Parameters

Request Examples

cURL:

curl --request GET \
  --url 'https://<direct.gateway>/tweet/1668868113725550592/retweets?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const response = await fetch('https://<direct.gateway>/tweet/1668868113725550592/retweets?count=20', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const data = await response.json();

Python:

import requests
 
response = requests.get(
    'https://<direct.gateway>/tweet/1668868113725550592/retweets',
    params={'count': 20},
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
data = response.json()

Response Example

{
  "entries": [
    {
      "type": "TimelineAddEntries",
      "entries": [
        {
          "entryId": "user-1968798245309583360",
          "content": {
            "itemContent": {
              "user_results": {
                "result": {
                  "rest_id": "1968798245309583360",
                  "legacy": {
                    "screen_name": "example_user",
                    "name": "Example User",
                    "followers_count": 1523,
                    "verified": false,
                    "profile_image_url_https": "https://pbs.twimg.com/profile_images/..."
                  }
                }
              }
            }
          }
        }
      ]
    }
  ],
  "cursor": {
    "top": "HCaAgICf6ZL3lTMAAA==",
    "bottom": "HBbq7uzA7avBpjIAAA=="
  }
}

Response Fields

Common Use Cases

1. Influencer identification: Find users with large followings who retweeted
2. Audience analysis: Understand who is sharing your content
3. Viral tracking: Monitor how tweets spread through retweets
4. Engagement metrics: Calculate potential reach based on retweeter followers

Notes

• Results are ordered by retweet time (most recent first)
• Use pagination cursors to retrieve all retweeters for popular tweets
• Private accounts that retweeted may not appear in results if you don't follow them

Best Practices

Tweet-Specific Tips

• Cache tweet data: Tweets don't change after posting, cache for 5-15 minutes
• Extract data efficiently: Response structure is nested - use helper functions to extract relevant fields
• Handle media: Media URLs are in legacy.extended_entities.media field
• Process replies: Use pagination to get all replies, not just the first page

Troubleshooting

FAQ

Can I get deleted tweets?

No, deleted tweets return a 404 error. Once a tweet is deleted, it cannot be retrieved through the API.

How do I get all replies to a tweet?

Use the main tweet endpoint with pagination. Set count=100 (maximum) and use the cursor parameter to paginate through all replies.

Can I access tweets from private accounts?

Yes, if your API credentials have access to the private account (i.e., you follow them). Otherwise, you'll receive a 403 Forbidden error.

What's the difference between tweet ID formats?

Tweet IDs are always numeric strings. The rest_id field in responses is the standard format. Some older systems may use different formats, but they all represent the same tweet.

How often is tweet data updated?

Tweet data (metrics, replies, etc.) is updated in real-time. However, for performance, consider caching data for a few minutes if you don't need real-time accuracy.

Can I get historical tweets?

Yes, as long as the tweet hasn't been deleted. Tweet IDs are permanent and can be used to retrieve tweets from any time period.

What media formats are supported?

The API supports all Twitter media formats including:

• Images (JPG, PNG, GIF, WebP)
• Videos (MP4)
• Animated GIFs
• Media are included in the legacy.extended_entities.media field

Related Documentation

• Users Endpoints - Get user information and timelines
• Search Endpoints - Search for tweets
• Using Pagination Cursors - Detailed cursor usage guide
• Error Handling Guide - Comprehensive error handling
• Rate Limits Guide - Understanding rate limits
• Best Practices - API usage best practices