The X API v2 returns minimal data by default. Use fields parameters to request additional data for each object type.
How fields work
By default, a post lookup returns only id, text, and edit_history_tweet_ids. To get more data, add field parameters to your request:
# Default response - minimal fields
curl "https://api.x.com/2/tweets/1234567890" \
-H "Authorization: Bearer $TOKEN"
# With additional fields
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,author_id" \
-H "Authorization: Bearer $TOKEN"
Available field parameters
Each object type has its own fields parameter:
| Object | Parameter | Documentation |
|---|
| Post (Tweet) | tweet.fields | Post fields |
| User | user.fields | User fields |
| Media | media.fields | Media fields |
| Poll | poll.fields | Poll fields |
| Place | place.fields | Place fields |
Example: Post fields
Request specific post fields with tweet.fields:
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,lang" \
-H "Authorization: Bearer $TOKEN"
{
"data": {
"id": "1234567890",
"text": "Hello world!",
"edit_history_tweet_ids": ["1234567890"],
"created_at": "2024-01-15T12:00:00.000Z",
"lang": "en",
"public_metrics": {
"retweet_count": 10,
"reply_count": 5,
"like_count": 100,
"quote_count": 2
}
}
}
Example: User fields
Request specific user fields with user.fields:
curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
-H "Authorization: Bearer $TOKEN"
{
"data": {
"id": "2244994945",
"name": "X Developers",
"username": "xdevelopers",
"created_at": "2013-12-14T04:35:55.000Z",
"description": "The voice of the X Developer Platform",
"public_metrics": {
"followers_count": 570842,
"following_count": 2048,
"tweet_count": 14052,
"listed_count": 1672
}
}
}
To get fields on related objects (like the author of a post), you need two things:
- An expansion to include the related object
- The fields parameter for that object type
# Get post with author details
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id&user.fields=description,public_metrics" \
-H "Authorization: Bearer $TOKEN"
{
"data": {
"id": "1234567890",
"text": "Hello world!",
"author_id": "2244994945"
},
"includes": {
"users": [{
"id": "2244994945",
"name": "X Developers",
"username": "xdevelopers",
"description": "The voice of the X Developer Platform",
"public_metrics": {
"followers_count": 570842,
"following_count": 2048
}
}]
}
}
Common field combinations
Post analytics
User profiles
Full post context
Media details
tweet.fields=created_at,public_metrics,possibly_sensitive
user.fields=created_at,description,location,public_metrics,verified
tweet.fields=created_at,author_id,conversation_id,in_reply_to_user_id,referenced_tweets
expansions=author_id,referenced_tweets.id
user.fields=username,name
tweet.fields=attachments
expansions=attachments.media_keys
media.fields=url,preview_image_url,alt_text,public_metrics
Important notes
You cannot request subfields. When you request public_metrics, you get all metrics (likes, reposts, replies, quotes). You can’t request just public_metrics.like_count.
- Field order in responses may differ from request order
- Missing fields in responses mean the value is
null or empty
- Some fields require specific authentication (e.g., private metrics need user context)
- Check each endpoint’s API reference for available fields
Next steps
