Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.x.com/llms.txt

Use this file to discover all available pages before exploring further.

Expansions let you include related objects in a single API response. Instead of making multiple requests, get a post and its author, media, or referenced posts in one call.

​
How expansions work

When you request an expansion, the API includes the full object in the includes section of the response: 
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id" \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "author_id": "2244994945"
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers"
    }]
  }
}
The author_id in data links to the user object in includes.

​
Post expansions

ExpansionReturnsUse case
author_idUser objectGet post author details
referenced_tweets.idPost object(s)Get quoted/replied-to posts
referenced_tweets.id.author_idUser object(s)Get authors of referenced posts
in_reply_to_user_idUser objectGet user being replied to
attachments.media_keysMedia object(s)Get images, videos, GIFs
attachments.poll_idsPoll objectGet poll options and votes
geo.place_idPlace objectGet location details
entities.mentions.usernameUser object(s)Get mentioned users
edit_history_tweet_idsPost object(s)Get previous versions of edited posts

​
User expansions

ExpansionReturnsUse case
pinned_tweet_idPost objectGet user’s pinned post

​
Space expansions

ExpansionReturnsUse case
creator_idUser objectGet Space creator
host_idsUser object(s)Get Space hosts
speaker_idsUser object(s)Get Space speakers
invited_user_idsUser object(s)Get invited users

​
DM expansions

ExpansionReturnsUse case
sender_idUser objectGet message sender
participant_idsUser object(s)Get conversation participants
attachments.media_keysMedia objectGet attached media
referenced_tweets.idPost objectGet referenced post

​
List expansions

ExpansionReturnsUse case
owner_idUser objectGet list owner

​
Combining with fields

Expansions return default fields for each object. To get additional fields, combine expansions with field parameters: 
curl "https://api.x.com/2/tweets/1234567890?\
expansions=author_id,attachments.media_keys&\
user.fields=description,public_metrics&\
media.fields=url,alt_text" \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "data": {
    "id": "1234567890",
    "text": "Check out this image!",
    "author_id": "2244994945",
    "attachments": {
      "media_keys": ["3_1234567890"]
    }
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers",
      "description": "The voice of the X Developer Platform",
      "public_metrics": {
        "followers_count": 570842
      }
    }],
    "media": [{
      "media_key": "3_1234567890",
      "type": "photo",
      "url": "https://pbs.twimg.com/media/example.jpg",
      "alt_text": "Example image"
    }]
  }
}

​
Multiple expansions

Request multiple expansions as a comma-separated list: 
expansions=author_id,referenced_tweets.id,attachments.media_keys

​
Common patterns

Get a post with author, media, and referenced posts:
expansions=author_id,attachments.media_keys,referenced_tweets.id
tweet.fields=created_at,public_metrics,conversation_id
user.fields=username,name,profile_image_url
media.fields=url,preview_image_url,type

​
Linking data and includes

The objects in includes don’t contain position information. Link them using IDs: 
# Python example
response = api_call()
post = response["data"]
users = {u["id"]: u for u in response["includes"]["users"]}

# Get the author
author = users.get(post["author_id"])
print(f"{author['name']} said: {post['text']}")

// JavaScript example
const { data: post, includes } = response;
const users = Object.fromEntries(
  includes.users.map(u => [u.id, u])
);

const author = users[post.author_id];
console.log(`${author.name} said: ${post.text}`);

​
Next steps

Fields

Request specific fields for each object.

Data Dictionary

Complete object schemas.