Fields

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"

Response:

{
  "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,
      "bookmark_count": 3,
      "impression_count": 1500
    }
  }
}

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"

Response:

{
  "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"

Response:

{
  "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
      }
    }]
  }
}

Learn more about expansions →

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, bookmarks, impressions). 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

Fields

How fields work

Available field parameters

Example: Post fields

Example: User fields

Common field combinations

Important notes

Next steps

Expansions

Data Dictionary

​How fields work

​Available field parameters

​Example: Post fields

​Example: User fields

​Fields for related objects

​Common field combinations

​Important notes

​Next steps

Expansions

Data Dictionary

How fields work

Available field parameters

Example: Post fields

Example: User fields

Fields for related objects

Common field combinations

Important notes

Next steps