X API v2 data dictionary: Post, User, Space fields

The X API returns rich structured JSON. This dictionary documents every available field for each object type.

Post (Tweet) fields
User fields
Space, List, Media, Poll, Place, Community, DM events
How to request fields & expansions
Example payloads

Full detailed field tables → Data Dictionary Reference

Object	Description	Fields parameter
Post (Tweet)	Posts, replies, reposts, quotes	`tweet.fields`
User	Account profiles and metadata	`user.fields`
Space	Live audio conversations	`space.fields`
List	Curated collections of accounts	`list.fields`
Media	Images, videos, GIFs	`media.fields`
Poll	Poll questions and options	`poll.fields`
Place	Location and geo data	`place.fields`

Use fields parameters to request specific fields, and expansions to include related objects.

Post (Tweet)

Posts are the core content unit on X. Each Post object includes text, metadata, and references to related objects like authors, media, and polls. Default fields: id, text, edit_history_tweet_ids Use tweet.fields to request additional fields and expansions to include related objects.

All Post fields

Field Value	Type	Description	How it Can Be Used
id (default)	string	The unique identifier of the requested Tweet.	Use this to programmatically retrieve a specific Tweet.
text (default)	string	The actual UTF-8 text of the Tweet. See twitter-text for details on valid characters.	Keyword extraction and sentiment analysis/classification.
edit_history_tweet_ids (default)	object	Unique identifiers indicating all versions of a Tweet. For Tweets with no edits, there will be one ID. For Tweets with an edit history, there will be multiple IDs.	Use this information to find the edit history of a Tweet.
article	object	Contains metadata for the Article present in this Tweet.	Use this to get the text and entities of an Article.
attachments	object	Specifies the type of attachments (if any) present in this Tweet.	Understanding the objects returned for requested expansions.
author_id	string	The unique identifier of the User who posted this Tweet.	Hydrating User object, sharing dataset for peer review.
card_uri	string	The URI for the Card present in this tweet.
community_id	string	The unique identifier for the Community this Post belongs to.
context_annotations	array	Contains context annotations for the Tweet.	Entity recognition/extraction, topical analysis.
conversation_id	string	The Tweet ID of the original Tweet of the conversation (which includes direct replies, replies of replies).	Use this to reconstruct the conversation from a Tweet.
created_at	date (ISO 8601)	Creation time of the Tweet.	Useful for time-series analysis and understanding when a Tweet was created.
display_text_range	array	An array containing a start and end index for the portion of text that gets displayed.	Useful for knowing which portion of text is displayed by default for long posts.
edit_controls	object	Indicates how much longer the Tweet can be edited and the number of remaining edits.	Use this to determine if a Tweet is eligible for editing.
entities	object	Entities that have been parsed out of the text of the Tweet. See entities in Twitter Objects.	Provides additional information about hashtags, URLs, mentions, etc.
geo	object	Indicates the location or place of a geo-tagged Tweet.	Use this to determine get location of a geo-tagged Tweet.
in_reply_to_user_id	string	If the represented Tweet is a reply, this field will contain the original Tweet’s author ID.	Determine if a Tweet was in reply to another Tweet.
lang	string	Language of the Tweet, if detected by Twitter.	Classify Tweets by spoken language.
non_public_metrics	object	Non-public engagement metrics for the Tweet at the time of the request. Requires user context authentication. Includes `impression_count`, `user_profile_clicks`, `url_link_clicks`, and `engagements`.	Determine total impressions and engagement generated for the Tweet.
note_tweet	object	Contains the full text of a Post for long-form Posts (>280 characters).	Get the complete text of a post.
organic_metrics	object	Engagement metrics, tracked in an organic context, for the Tweet at the time of the request. Requires user context authentication.	Measure organic engagement for the Tweet.
paid_partnership	boolean	Indicates if this Post is a paid partnership, i.e., it has been disclosed by the author as containing paid promotion.	Identify Posts disclosed as paid partnerships / sponsored content.
possibly_sensitive	boolean	Indicates if the content may be recognized as sensitive.	Study circulation of certain types of content.
promoted_metrics	object	Engagement metrics, tracked in a promoted context, for the Tweet at the time of the request. Requires user context authentication.	Measure engagement for the Tweet when it was promoted.
public_metrics	object	Public engagement metrics for the Tweet at the time of the request. Includes `retweet_count`, `reply_count`, `like_count`, `quote_count`, `impression_count`, and `bookmark_count`.	Measure Tweet engagement.
referenced_tweets	array	A list of Tweets this Tweet refers to, such as Retweets, quoted Tweets, or replies.	Understand conversational aspects of retweets, etc.
reply_settings	string	Shows who can reply to a given Tweet. Options are “everyone”, “mentioned_users”, and “followers”.	Determine conversation reply settings for the Tweet.
withheld	object	Contains withholding details for withheld content.
scopes	object	Contains scope details for the tweet.	Indicates who can view the post. Only returned for promoted posts.
media_metadata	array	Contains metadata for media attachments of the Tweet.	Get additional metadata like the `alt_text` of a Tweet’s media attachment.

Retrieving a Tweet Object Sample Request In the following request, we are requesting fields for the Tweet on the Tweets lookup endpoint. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

curl --request GET 'https://api.x.com/2/tweets?ids=1212092628029698048&tweet.fields=attachments,author_id,context_annotations,created_at,entities,geo,id,in_reply_to_user_id,lang,paid_partnership,possibly_sensitive,public_metrics,referenced_tweets,text,withheld&expansions=referenced_tweets.id' --header 'Authorization: Bearer $BEARER_TOKEN'

Sample Response

{
  "data": [
    {
      "text": "We believe the best future version of our API will come from building it with YOU. Here’s to another great year with everyone who builds on the Twitter platform. We can’t wait to continue working with you in the new year. https://t.co/yvxdK6aOo2",
      "edit_history_tweet_ids": [
        "1212092628029698048"
      ],
      "lang": "en",
      "in_reply_to_user_id": "2244994945",
      "entities": {
        "urls": [
          {
            "start": 222,
            "end": 245,
            "url": "https://t.co/yvxdK6aOo2",
            "expanded_url": "https://x.com/LovesNandos/status/1211797914437259264/photo/1",
            "display_url": "pic.x.com/yvxdK6aOo2",
            "media_key": "16_1211797899316740096"
          }
        ],
        "annotations": [
          {
            "start": 42,
            "end": 44,
            "probability": 0.5359,
            "type": "Other",
            "normalized_text": "API"
          },
          {
            "start": 144,
            "end": 150,
            "probability": 0.9832,
            "type": "Other",
            "normalized_text": "Twitter"
          }
        ]
      },
      "author_id": "2244994945",
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1212092627178287104"
        }
      ],
      "id": "1212092628029698048",
      "public_metrics": {
        "retweet_count": 7,
        "reply_count": 3,
        "like_count": 38,
        "quote_count": 1,
        "bookmark_count": 2,
        "impression_count": 1250
      },
      "context_annotations": [
        {
          "domain": {
            "id": "29",
            "name": "Events [Entity Service]",
            "description": "Real world events. "
          },
          "entity": {
            "id": "1186637514896920576",
            "name": " New Years Eve"
          }
        },
        {
          "domain": {
            "id": "29",
            "name": "Events [Entity Service]",
            "description": "Real world events. "
          },
          "entity": {
            "id": "1206982436287963136",
            "name": "Happy New Year: It’s finally 2020 everywhere!",
            "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
          }
        },
        {
          "domain": {
            "id": "119",
            "name": "Holiday",
            "description": "Holidays like Christmas or Halloween"
          },
          "entity": {
            "id": "1186637514896920576",
            "name": " New Years Eve"
          }
        },
        {
          "domain": {
            "id": "119",
            "name": "Holiday",
            "description": "Holidays like Christmas or Halloween"
          },
          "entity": {
            "id": "1206982436287963136",
            "name": "Happy New Year: It’s finally 2020 everywhere!",
            "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
          }
        },
        {
          "domain": {
            "id": "30",
            "name": "Entities [Entity Service]",
            "description": "Entity Service top level domain, every item that is in Entity Service should be in this domain"
          },
          "entity": {
            "id": "781974596752842752",
            "name": "Services"
          }
        },
        {
          "domain": {
            "id": "47",
            "name": "Brand",
            "description": "Brands and Companies"
          },
          "entity": {
            "id": "10045225402",
            "name": "Twitter"
          }
        },
        {
          "domain": {
            "id": "131",
            "name": "Unified Twitter Taxonomy",
            "description": "A taxonomy of user interests. "
          },
          "entity": {
            "id": "10045225402",
            "name": "Twitter"
          }
        },
        {
          "domain": {
            "id": "131",
            "name": "Unified Twitter Taxonomy",
            "description": "A taxonomy of user interests. "
          },
          "entity": {
            "id": "847868745150119936",
            "name": "Family & relationships",
            "description": "Hobbies and interests"
          }
        },
        {
          "domain": {
            "id": "131",
            "name": "Unified Twitter Taxonomy",
            "description": "A taxonomy of user interests. "
          },
          "entity": {
            "id": "1196446161223028736",
            "name": "Social media"
          }
        },
        {
          "domain": {
            "id": "29",
            "name": "Events [Entity Service]",
            "description": "Real world events. "
          },
          "entity": {
            "id": "1206982436287963136",
            "name": "Happy New Year: It’s finally 2020 everywhere!",
            "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
          }
        },
        {
          "domain": {
            "id": "119",
            "name": "Holiday",
            "description": "Holidays like Christmas or Halloween"
          },
          "entity": {
            "id": "1206982436287963136",
            "name": "Happy New Year: It’s finally 2020 everywhere!",
            "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
          }
        }
      ],
      "created_at": "2019-12-31T19:26:16.000Z",
      "attachments": {
        "media_keys": [
          "16_1211797899316740096"
        ]
      },
      "possibly_sensitive": false
    }
  ],
  "includes": {
    "tweets": [
      {
        "text": "These launches would not be possible without the feedback you provided along the way, so THANK YOU to everyone who has contributed your time and ideas. Have more feedback? Let us know ⬇️ https://t.co/Vxp4UKnuJ9",
        "edit_history_tweet_ids": [
          "1212092627178287104"
        ],
        "lang": "en",
        "in_reply_to_user_id": "2244994945",
        "entities": {
          "urls": [
            {
              "start": 187,
              "end": 210,
              "url": "https://t.co/Vxp4UKnuJ9",
              "expanded_url": "https://twitterdevfeedback.uservoice.com/forums/921790-twitter-developer-labs",
              "display_url": "twitterdevfeedback.uservoice.com/forums/921790-…",
              "status": 200,
              "title": "Updates on our feedback channels",
              "description": "We build our developer platform in the open, with your input and feedback. Over the past year, hearing directly from you and the users of your apps has helped us build developer products that cater to the use case you helped us identify. We want to make this the way we build products, and moving forward, we are consolidating our feedback channels. Meeting you where you are Effective today, we are going to retire our UserVoice feedback channel in favor of more frequent direct engagements with y...",
              "unwound_url": "https://devcommunity.x.com/t/updates-on-our-feedback-channels/169706"
            }
          ]
        },
        "author_id": "2244994945",
        "referenced_tweets": [
          {
            "type": "replied_to",
            "id": "1212092626247110657"
          }
        ],
        "id": "1212092627178287104",
        "public_metrics": {
          "retweet_count": 2,
          "reply_count": 1,
          "like_count": 19,
          "quote_count": 0,
          "bookmark_count": 0,
          "impression_count": 430
        },
        "created_at": "2019-12-31T19:26:16.000Z",
        "possibly_sensitive": false
      }
    ]
  }

User

The user object contains Twitter user account metadata describing the referenced user. The user object is the primary object returned in the users lookup endpoint. When requesting additional user fields on this endpoint, simply use the fields parameter user.fields. The user object can also be found as a child object and expanded in the Tweet object. The object is available for expansion with ?expansions=author_id or ?expansions=in_reply_to_user_id to get the condensed object with only default fields. Use the expansion with the field parameter: user.fields when requesting additional fields to complete the object.

Field value	Type	Description	How it can be used
id (default)	string	The unique identifier of this user. `"id": "2244994945"`	Use this to programmatically retrieve information about a specific Twitter user.
name (default)	string	The name of the user, as they’ve defined it on their profile. Not necessarily a person’s name. Typically capped at 50 characters, but subject to change. `"name": "Twitter Dev"`
username (default)	string	The Twitter screen name, handle, or alias that this user identifies themselves with. Usernames are unique but subject to change. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names. `"username": "TwitterDev"`
affiliation	object	Contains details about a user’s affiliation.	Can be used to get a user’s affiliate badge.
confirmed_email	string	The confirmed email of the authenticated user.
connection_status	array	Provides a list of relation between the authenticating user and the user being looked up such as following, followed, follow request sent, follow request received, blocking, muting. `"connection_status": ["follow_request_received", "follow_request_sent", "blocking", "followed_by", "following", "muting"]`	Can be used to determine the connection status between the authenticating user and the user being looked up.
created_at	date (ISO 8601)	The UTC datetime that the user account was created on Twitter. `"created_at": "2013-12-14T04:35:55.000Z"`	Can be used to determine how long a someone has been using Twitter
description	string	The text of this user’s profile description (also known as bio), if the user provided one. `"description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X API."`
entities	object	Contains details about text that has a special meaning in the user’s description. Includes nested `url` and `description` objects, each containing arrays such as `urls`, `hashtags`, `mentions`, and `cashtags`. See the sample response below for a complete example.	Entities are JSON objects that provide additional information about hashtags, urls, user mentions, and cashtags associated with the description. Reference each respective entity for further details. All user start indices are inclusive, while all user end indices are exclusive.
is_identity_verified	boolean	Indicates if the user is ID verified.
location	string	The location specified in the user’s profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries. `"location": "127.0.0.1"`
most_recent_tweet_id	string	Unique identifier of this user’s most recent Tweet.	Determine the most recent Tweet of the user.
parody	boolean	Indicates whether or not this user account has the Parody label.
pinned_tweet_id	string	Unique identifier of this user’s pinned Tweet. `"pinned_tweet_id": "1255542774432063488"`	Determine the Tweet pinned to the top of the user’s profile. Can potentially be used to determine the user’s language.
profile_banner_url	string	The URL to the profile banner for this user, as shown on the user’s profile. `"profile_banner_url": "https://pbs.twimg.com/profile_banners/1716450569358098432/1721022977"`	Can be used to download this user’s profile banner.
profile_image_url	string	The URL to the profile image for this user, as shown on the user’s profile. `"profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg"`	Can be used to download this user’s profile image.
protected	boolean	Indicates if this user has chosen to protect their Tweets (in other words, if this user’s Tweets are private). `"protected": false`
public_metrics	object	Contains details about activity for this user. `"public_metrics": {"followers_count": 507902, "following_count": 1863, "tweet_count": 3561, "listed_count": 1550}`	Can potentially be used to determine a Twitter user’s reach or influence, quantify the user’s range of interests, and the user’s level of engagement on Twitter.
receives_your_dm	boolean	Indicates whether or not this user will receive the authenticated user’s DM.
subscription	object	Contains details on whether or not the user is subscribed to the authenticated user.
subscription_type	string	A string representing the type of X Premium subscription the authenticated user has. Example: `None`, `Basic`, `Premium`,`PremiumPlus`. Will always return `None` if the user is not the authenticated user.
url	string	The URL specified in the user’s profile, if present. `"url": "https://t.co/3ZX3TNiZCY"`	A URL provided by a Twitter user in their profile. This could be a homepage, but is not always the case.
verified	boolean	Indicates if this user is a verified Twitter User. `"verified": true`	Indicates whether or not this Twitter user has a verified account. A verified account lets people know that an account of public interest is authentic.
verified_followers_count	string	A string representing the number of verified followers of a user.
verified_type	string	A string representing the type of verification a user has. Example: “blue”, “business”, “government”
withheld	object	Contains withholding details for withheld content, if applicable.

Retrieving a user object Sample Request In the following request, we are requesting fields for the user on the users lookup endpoint. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

  curl --request GET 'https://api.x.com/2/users?
  ids=2244994945&user.fields=created_at,description,entities,id,location,name,pinned_tweet_id,profile_image_url,protected,url,username,verified,withheld&expansions=pinned_tweet_id'
  --header 'Authorization: Bearer $BEARER_TOKEN'
  }

Sample Response

"data": [
  {
      "id": "2244994945",
      "name": "Twitter Dev",
      "username": "TwitterDev",
      "location": "127.0.0.1",
      "entities": {
          "url": {
              "urls": [
                  {
                      "start": 0,
                      "end": 23,
                      "url": "https://t.co/3ZX3TNiZCY",
                      "expanded_url": "/content/developer-twitter/en/community",
                      "display_url": "developer.x.com/en/community"
                  }
              ]
          },
          "description": {
              "hashtags": [
                  {
                      "start": 23,
                      "end": 30,
                      "tag": "DevRel"
                  },
                  {
                      "start": 113,
                      "end": 130,
                      "tag": "BlackLivesMatter"
                  }
              ]
          }
      },
      "verified": true,
      "description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API. \n\n#BlackLivesMatter",
      "url": "https://t.co/3ZX3TNiZCY",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg",
      "protected": false,
      "pinned_tweet_id": "1255542774432063488",
      "created_at": "2013-12-14T04:35:55.000Z"
  }
],
"includes": {
  "tweets": [
      {
          "id": "1255542774432063488",
          "text": "During these unprecedented times, what’s happening on Twitter can help the world better understand &amp; respond to the pandemic. \n\nWe're launching a free COVID-19 stream endpoint so qualified devs &amp; researchers can study the public conversation in real-time. https://t.co/BPqMcQzhId"
      }
  ]
}
}

Space

Spaces allow expression and interaction via live audio conversations. The Space data dictionary contains relevant metadata about a Space; all the details are updated in real time. User objects can be found and expanded in the user resource. These objects are available for expansion by adding at least one of host_ids, creator_id, speaker_ids, mentioned_user_ids to the expansions query parameter. Unlike Tweets, Spaces are ephemeral and become unavailable after they end or when they are canceled by their creator. When your app handles Spaces data, you are responsible for returning the most up-to-date information and must remove data that is no longer available from the platform. The Spaces lookup endpoints can help you ensure you respect the users’ expectations and intent.

Field Value	Type	Description	How it can be used
id (default)	string	The unique identifier of the requested Space. `"id": "1zqKVXPQhvZJB"`	Uniquely identify a Space returned in the response.
state (default)	string	Indicates if the Space has started, will start, or has ended. `"state": "live"`	Filter live or scheduled Spaces.
created_at	date (ISO 8601)	Creation time of this Space. `"created_at": "2021-07-04T23:12:08.000Z"`	Understand when a Space was created and sort by time.
creator_id	string	Unique identifier of the Space creator. `"creator_id": "2244994945"`
ended_at	date (ISO 8601)	Time when the Space ended, if applicable. `"ended_at": "2021-07-04T00:11:44.000Z"`	Determine when a live Space ended for runtime duration.
host_ids	array	Unique identifiers of the Space hosts. `"host_ids": ["2244994945", "6253282"]`	Expand User objects, understand engagement.
lang	string	Language of the Space, if detected. `"lang": "en"`	Classify Spaces by language.
is_ticketed	boolean	Indicates if this is a ticketed Space. `"is_ticketed": false`	Highlight content of interest.
invited_user_ids	array	List of user IDs invited as speakers. `"invited_user_ids": ["2244994945", "6253282"]`	Expand User objects, understand engagement.
participant_count	integer	Number of users in the Space, including Hosts and Speakers. `"participant_count": 420`	Understand engagement, create reports.
subscriber_count	integer	Number of people who set a reminder for a Space. `"subscriber_count": 36`	Understand event interest.
scheduled_start	date (ISO 8601)	Scheduled start time of the Space. `"scheduled_start": "2021-07-14T08:00:00.000Z"`	Integrate with calendar notifications.
speaker_ids	array	List of users who spoke at any point. `"speaker_ids": ["2244994945", "6253282"]`	Expand User objects, understand engagement.
started_at	date (ISO 8601)	Actual start time of a Space. `"started_at": "2021-07-14T08:00:12.000Z"`	Determine Space start time.
title	string	Title of the Space. `"title": "Say hello to the Space data object!"`	Understand keywords, hashtags, mentions.
topic_ids	array	IDs of topics selected by the Space creator. `"topic_ids": ["2244994945", "6253282"]`	Understand keywords, hashtags, mentions.
updated_at	date (ISO 8601)	Last update to Space metadata. `"updated_at": "2021-07-11T14:44:44.000Z"`	Keep information up to date.

**Retrieving a Space Object ** Sample Request In the following request, we are requesting fields for the Space on the Spaces lookup endpoint. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?space.fields=created_at,creator_id,created_athost_ids,lang,is_ticketed,invited_user_ids,participant_count,scheduled_start,speaker_ids,started_at,state,title,updated_at&expansions=creator_id,host_ids,invited_user_ids,speaker_ids" --header "Authorization: Bearer $BEARER_TOKEN"

** Sample Response **

{
  "data": {
    "id": "1zqKVXPQhvZJB",
    "state": "live",
    "created_at": "2021-07-04T23:12:08.000Z",
    "host_ids": [
      "2244994945",
      "6253282"
    ],
    "lang": "en",
    "is_ticketed": false,
    "invited_user_ids": [
      "2244994945",
      "6253282"
    ],
    "participant_count": 420,
    "scheduled_start": "2021-07-14T08:00:00.000Z",
    "speaker_ids": [
      "2244994945",
      "6253282"
    ],
    "started_at": "2021-07-14T08:00:12.000Z",
    "title": "Say hello to the Space data object!",
    "updated_at": "2021-07-11T14:44:44.000Z"
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      },
      {
        "id": "6253282",
        "name": "Twitter API",
        "username": "TwitterAPI"
      }
    ]
  }
}

List

The list object contains Twitter Lists metadata describing the referenced List. The List object is the primary object returned in the List lookup endpoint. When requesting additional List fields on this endpoint, simply use the fields parameter list.fields. The List object is not found as a child of other data objects. However, user objects can be found and expanded in the user resource. These objects are available for expansion by adding owner_id to the expansions query parameter. Use this expansion with the list.fields field parameter when requesting additional fields to complete the primary List object and user.fields to complete the expansion object.

Field Value	Type	Description	How it can be used
id (default)	string	The unique identifier of this List. `"id": "2244994945"`	Use this to programmatically retrieve information about a specific List.
name (default)	string	The name of the List, as defined when creating the List. `"name": "Twitter Lists"`
created_at	date (ISO 8601)	The UTC datetime when the List was created. `"created_at": "2013-12-14T04:35:55.000Z"`	Determine how long a List has been on Twitter.
description	string	A brief description to inform users about the List. `"description": "People that are active members of the Bay area cycling community on Twitter."`
follower_count	integer	Shows how many users follow this List. `"follower_count": 198`
member_count	integer	Shows how many members are part of this List. `"member_count": 60`
private	boolean	Indicates if the List is private. `"private": false`
owner_id	string	Unique identifier of this List’s owner. `"owner_id": "1255542774432063488"`	Can be used to find out if this user owns other Lists and expand User objects.

Retrieving a User Object Sample Request In the following request, we are requesting fields for the user on the List lookup by ID endpoint. Replace $BEARER_TOKEN with your generated Bearer Token.

curl --request GET 'https://api.x.com/2/lists/1355797419175383040?list.fields=created_at,description,private,follower_count,member_count,owner_id&expansions=owner_id' --header 'Authorization: Bearer $BEARER_TOKEN'

** Sample Response**

{
  "data": {
    "name": "Twitter Comms",
    "member_count": 60,
    "id": "1355797419175383040",
    "private": false,
    "description": "",
    "follower_count": 198,
    "owner_id": "257366942",
    "created_at": "2021-01-31T08:37:48.000Z"
  },
  "includes": {
    "users": [
      {
        "created_at": "2011-02-25T07:51:26.000Z",
        "name": "Ashleigh Hay 🤸🏼‍♀️",
        "id": "257366942",
        "username": "shleighhay",
        "verified": false
      }
    ]
  }
}

Media

Media refers to any image, GIF, or video attached to a Tweet. The media object is not a primary object on any endpoint, but can be found and expanded in the Tweet object. The object is available for expansion with ?expansions=attachments.media_keys to get the condensed object with only default fields. Use the expansion with the field parameter: media.fields when requesting additional fields to complete the object.

Field value	Type	Description	How it can be used
media_key (default)	string	Unique identifier of the expanded media content. `"media_key": "13_1263145212760805376"`	Can be used to programmatically retrieve media
type (default)	string	Type of content (animated_gif, photo, video). `"type": "video"`	Classify the media as a photo, GIF, or video
url	string	A direct URL to the media file on Twitter.	Returns a Media object with a URL field for photos
duration_ms	integer	Available when type is video. Duration in milliseconds of the video. `"duration_ms": 46947`
height	integer	Height of this content in pixels. `"height": 1080`
non_public_metrics	object	Non-public engagement metrics for the media content at the time of the request. Requires user context authentication. `"non_public_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183,}`	Determine video engagement: how many users played through to each quarter of the video.
organic_metrics	object	Engagement metrics for the media content, tracked in an organic context, at the time of the request. Requires user context authentication. `"organic_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183, "view_count": 629}`	Determine organic media engagement.
preview_image_url	string	URL to the static placeholder preview of this content. `"preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg"`
promoted_metrics	object	Engagement metrics for the media content, tracked in a promoted context, at the time of the request. Requires user context authentication. `"promoted_metrics": { "playback_0_count": 259, "playback_100_count": 15, "playback_25_count": 113, "playback_50_count": 57, "playback_75_count": 25, "view_count": 124}`	Determine media engagement when the Tweet was promoted.
public_metrics	object	Public engagement metrics for the media content at the time of the request. `"public_metrics": { "view_count": 6865141}`	Determine total number of views for the video attached to the Tweet.
width	integer	Width of this content in pixels. `"width": 1920`
alt_text	string	A description of an image to enable and support accessibility. Can be up to 1000 characters long. Alt text can only be added to images at the moment. `"alt_text": "Rugged hills along the Na Pali coast on the island of Kauai"`	Can be used to provide a written description of an image in case a user is visually impaired.
variants	array	Each media object may have multiple display or playback variants, with different resolutions or formats. `"variants": [{ "bit_rate": 632000, "content_type": "video/mp4", "url": "https://video.twimg.com/ext_tw_video/1527322141724532740/pu/vid/320x568/lnBaR2hCqE-R_90a.mp4?tag=12"}]`

Retrieving a media object Sample Request In the following request, we are requesting fields for the media object attached to the Tweet on the Tweet lookup endpoint. Since media is a child object of a Tweet, the attachment.media_keys expansion is required. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

curl --request GET 'https://api.x.com/2/tweets?ids=1263145271946551300&expansions=attachments.media_keys&media.fields=duration_ms,height,media_key,preview_image_url,public_metrics,type,url,width,alt_text' --header 'Authorization: Bearer $BEARER_TOKEN'

{
  "data": [
    {
      "text": "Testing, testing...\n\nA new way to have a convo with exactly who you want. We’re starting with a small % globally, so keep your 👀 out to see it in action. https://t.co/pV53mvjAVT",
      "id": "1263145271946551300",
      "attachments": {
        "media_keys": [
          "13_1263145212760805376"
        ]
      }
    }
  ],
  "includes": {
    "media": [
      {
        "duration_ms": 46947,
        "type": "video",
        "height": 1080,
        "media_key": "13_1263145212760805376",
        "public_metrics": {
          "view_count": 6909260
        },
        "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg",
        "width": 1920
      }
    ]
  }
}

Poll

A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object. The object is available for expansion with ?expansions=attachments.poll_ids to get the condensed object with only default fields. Use the expansion with the field parameter: poll.fields when requesting additional fields to complete the object.

Field value	Type	Description
id (default)	string	Unique identifier of the expanded poll.
		`{"id": "1199786642791452673"}`
options (default)	array	Contains objects describing each choice in the referenced poll.
		`{"options": [ { "position": 1, "label": "“C Sharp”", "votes": 795 }, { "position": 2, "label": "“C Hashtag”", "votes": 156 } ]}`
duration_minutes	integer	Specifies the total duration of this poll.
		`{"duration_minutes": 1440}`
end_datetime	date (ISO 8601)	Specifies the end date and time for this poll.
		`{"end_datetime": "2019-11-28T20:26:41.000Z"}`
voting_status	string	Indicates if this poll is still active and can receive votes, or if the voting is now closed.
		`{"voting_status": "closed"}`

Retrieving a poll object Sample Request In the following request, we are requesting fields for the poll object attached to the Tweet on the Tweets lookup endpoint. Since poll is a child object of a Tweet, the attachments.poll_id expansion is required. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

curl --request GET 'https://api.x.com/2/tweets?ids=1199786642791452673&expansions=attachments.poll_ids&poll.fields=duration_minutes,end_datetime,id,options,voting_status' --header 'Authorization: Bearer $BEARER_TOKEN'

Sample Response

{
  "data": [
    {
      "text": "C#",
      "id": "1199786642791452673",
      "attachments": {
        "poll_ids": [
          "1199786642468413448"
        ]
      }
    }
  ],
  "includes": {
    "polls": [
      {
        "id": "1199786642468413448",
        "voting_status": "closed",
        "duration_minutes": 1440,
        "options": [
          {
            "position": 1,
            "label": "“C Sharp”",
            "votes": 795
          },
          {
            "position": 2,
            "label": "“C Hashtag”",
            "votes": 156
          }
        ],
        "end_datetime": "2019-11-28T20:26:41.000Z"
      }
    ]
  }
}

Place

The place tagged in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet resource. The object is available for expansion with ?expansions=geo.place_id to get the condensed object with only default fields. Use the expansion with the field parameter: place.fields when requesting additional fields to complete the object.

Field value	Type	Description	How it can be used
full_name (default)	string	A longer-form detailed place name.	Classify a Tweet by a specific place name
		`"full_name": "Manhattan, NY"`
id (default)	string	The unique identifier of the expanded place, if this is a point of interest tagged in the Tweet.	Use this to programmatically retrieve a place
		`"id": "01a9a39529b27f36"`
contained_within	array	Returns the identifiers of known places that contain the referenced place.
country	string	The full-length name of the country this place belongs to.	Classify a Tweet by country name
		`"country": "United States"`
country_code	string	The ISO Alpha-2 country code this place belongs to.	Classify a Tweet by country code
		`"country_code": "US"`
geo	object	Contains place details in GeoJSON format.
		```json
		”geo”:
		“type”: “Feature”,
		“bbox”: [
		-74.026675,
		40.683935,
		-73.910408,
		40.877483
		],
		“properties”:
		}
		```
name	string	The short name of this place.	Classify a Tweet by a specific place name
		`"name": "Manhattan"`
place_type	string	Specified the particular type of information represented by this place information, such as a city name, or a point of interest.	Classify a Tweet by a specific type of place
		`"place_type": "city"`

Retrieving a place object Sample Request In the following request, we are requesting fields for the place object attached to the Tweet on the Tweets lookup endpoint. Since place is a child object of a Tweet, the geo.place_id expansion is required. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

curl --request GET 'https://api.x.com/2/tweets?ids=1136048014974423040&expansions=geo.place_id&place.fields=contained_within,country,country_code,full_name,geo,id,name,place_type' --header 'Authorization: Bearer $BEARER_TOKEN'

Sample Response

{
  "data": [
    {
      "text": "We’re sharing a live demo of the new Twitter Developer Labs program, led by a member of our DevRel team, @jessicagarson #TapIntoTwitter https://t.co/ghv7f4dW5M",
      "id": "1136048014974423040",
      "geo": {
        "place_id": "01a9a39529b27f36"
      }
    }
  ],
  "includes": {
    "places": [
      {
        "geo": {
          "type": "Feature",
          "bbox": [
            -74.026675,
            40.683935,
            -73.910408,
            40.877483
          ],
          "properties": {}
        },
        "country_code": "US",
        "name": "Manhattan",
        "id": "01a9a39529b27f36",
        "place_type": "city",
        "country": "United States",
        "full_name": "Manhattan, NY"
      }
    ]
  }
}

Direct Message events

Direct Message (DM) conversations are made up of events. The X API v2 currently supports three event types: MessageCreate, ParticipantsJoin, and ParticipantsLeave. DM event objects are returned by the Direct Message lookup endpoints, and a MessageCreate event is created when Direct Messages are successfully created with the Manage Direct Messages endpoints. When requesting DM events, there are three default event object attributes, or fields, included: id, event_type, and text. To receive additional event fields, use the fields parameter dm_event.fields to select others. Other available event fields include the following: dm_conversation_id, created_at, sender_id, attachments, participant_ids, and referenced_tweets. Several of these fields provide the IDs of other X objects related to the Direct Message event:

sender_id - The ID of the account that sent the message, or who invited a participant to a group conversation
partricipants_ids - An array of account IDs. For ParticipantsJoin and ParticipantsLeave events this array will contain a single ID of the account that created the event
attachments - Provides media IDs for content that has been uploaded to Twitter by the sender
referenced_tweets - If a Tweet URL is found in the text field, the ID of that Tweet is included in the response

The sender_id, participant_ids, referenced_tweets.id, and attachments.media_keys expansions are available to expand on these Twitter object IDs.


Field value	Type	Description	How it can be used
id (default)	string	The unique identifier of the event. `"id": "1050118621198921728"`	Use this to programmatically retrieve a specific conversation event (available with v1.1 endpoints).
event_type (default)	string	Describes the type of event. Three types are currently supported: MessageCreate, ParticipantsJoin, and ParticipantsLeave. `"event_type": "MessageCreate"`	When retrieving a conversation’s history, understanding when messages were created, and for group conversations, understanding when participants joined and left. All GET methods support filtering on specific event types with the `event_type=` query parameter.
text (default)	string	The actual UTF-8 text of the Direct Message. `"text": "Hello, just you!"`	With chatbots, this can be used to analyze message contents and determining automated responses. Could be used to build conversation search features.
entities	object	Entities that have been parsed out of the text of the DM.	Provides additional information about hashtags, URLs, mentions, etc.
sender_id	string	ID of the User creating the event. To expand this object in the response, include sender_id as an expansion and use the user.fields query parameter to specify User object attributes of interest. `"sender_id": "906948460078698496"`	Retrieve the User object of who created the MessageCreate or ParticipantsJoin event.
participant_ids	array (of strings)	IDs of the participants joining and leaving a group conversation. Also used when creating new group conversations. To expand this object in the response, include participant_ids as an expansion and use the user.fields query parameter to specify User object attributes of interest. `"participant_ids": ["906948460078698496"]`	Used to retrieve User objects for participants joining and leaving group conversations.
dm_conversation_id	string	The unique identifier of the conversation the event is apart of. `"dm_conversation_id": "1584988213961031680"`	Use this to programmatically retrieve events from a conversation, and add Direct Messages to it.
created_at	date (ISO 8601)	Creation time (UTC) of the Tweet. `"created_at": "2019-06-04T23:12:08.000Z"`	This field can be used to understand when a Direct Message was created or when conversation participants joined or left.
referenced_tweets	array	ID for any Tweet mentioned in the Direct Message text. To expand this object in the response, include referenced_tweets.id as an expansion and use the tweet.fields query parameter to specify Tweet object attributes of interest. `"referenced_tweets": [{"id": "1578868150510456833"}]`	When Direct Messages reference a Tweet, these IDs can be used to lookup the Tweet’s details.
attachments	object	For Direct Messages with attached Media, provides the media key of the uploaded content (photo, video, or GIF). To expand this object in the response, include attachments.media_keys as an expansion and use the media.fields query parameter to specify media object attributes of interest. Currently, one attachment is supported. `"attachments": {"media_keys": ["3_1136048009270239232"]}`	Understanding the media objects attached to Direct Messages.

Retrieving a Direct Message event object Sample Request For this example, we will build a request that retrieves events associated with a one-to-one conversation. This request will return fundamental Direct Message event fields, along with additional fields for referenced Tweets and their authors. Let’s build a query that asks for:

Fundamental event attributes such as when it was created and what conversation it is part of (dm_conversation).
The account ID and description of who sent the Direct Message.
The text of any referenced Tweet, and when it was posted.
The account ID and description of any referenced Tweet author.

To return those attributes, your request query would include the following:

?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description

curl --request GET 'https://api.x.com/2/dm_conversations/with/:participant_id/dm_events?tweet.fields=created_at,text,author_id&user.fields=description&expansions=sender_id,participant_ids,referenced_tweets.id&dm_event.fields=id,sender_id,text,participant_ids,created_at,'
--header 'Authorization: Bearer $BEARER_TOKEN'

Be sure to replace $BEARER_TOKEN with your own generated Bearer Token. Sample Response

{
"data": [{
  	"id": "1585047616894574596",
  	"sender_id": "944480690",
  	"text": "Hello, just you!",
  	"created_at": "2022-10-25T23:16:15.000Z",
  	"event_type": "MessageCreate",
  	"dm_conversation_id": "944480690-906948460078698496"
  },
  {
  	"id": "1581048670673260549",
  	"sender_id": "944480690",
  	"text": "Simple Tweet link: https://t.co/IYFbRIdXHg",
  	"referenced_tweets": [{
  		"id": "1578900353814519810"
  	}],
  	"created_at": "2022-10-14T22:25:52.000Z",
  	"event_type": "MessageCreate",
  	"dm_conversation_id": "944480690-906948460078698496"
  },
  {
  	"id": "1580705121553420292",
  	"sender_id": "944480690",
  	"text": "Adding a new 1-to-1 Direct Message.",
  	"created_at": "2022-10-13T23:40:43.000Z",
  	"event_type": "MessageCreate",
  	"dm_conversation_id": "944480690-906948460078698496"
  }
],
"includes": {
  "users": [{
  		"name": "API Demos",
  		"description": "Hosting TwitterDev integrations... @TwitterDev #DevRel",
  		"id": "944480690",
  		"username": "FloodSocial"
  	},
  	{
  		"name": "the SnowBot",
  		"description": "Home of the @TwitterDev SnowBot... Serving snow reports, snow photos, and snow research links... Chatbot is currently being remodeled for Twitter APIv2.",
  		"id": "906948460078698496",
  		"username": "SnowBotDev"
  	}
  ],
  "tweets": [{
  		"text": "Feeling kind of bad that I didn’t wish everybody a happy new Colorado Water Year…\n\nHappy Water Year to all my Colorado friends and colleagues, new and old… \n\nMay this be a generous water year, although not too generous…",
  		"id": "1578900353814519810",
  		"created_at": "2022-10-09T00:09:13.000Z",
  		"author_id": "944480690",
  		"edit_history_tweet_ids": [
  			"1578900353814519810"
  		]
  	}
  ]
},
"meta": {
  "result_count": 3,
  "next_token": "18LAA581J5II7LA00C00ZZZZ",
  "previous_token": "1BLC45G1H8CAL5DG0G00ZZZZ"
}
}

Community

Communities are dedicated places for X users to connect, share, and get closer to the discussions they care about most. Posts in Communities can be seen by anyone on X, but only others within the Community itself can engage and participate in the discussion. The Community object contains relevant metadata about a Community.

Field value	Type	Description
created_at	date (ISO 8601)	Creation time of the Community.
id	string	The unique identifier of the Community.
name	string	The name of the Community.
description	string	The text of the Community’s description, if provided.
access	string	The access level of the Community. Can be one of:
		- `Public`
		- `Closed`
join_policy	string	The join policy for the Community. Can be one of:
		- `Open`
		- `RestrictedJoinRequestsDisabled`
		- `RestrictedJoinRequestsRequireAdminApproval`
		- `RestrictedJoinRequestsRequireModeratorApproval`
		- `SuperFollowRequired`
member_count	integer	The number of members that have joined the Community.

Retrieving Community objects Sample Request In the following request, we are requesting specific fields while searching for a list of Communities based on a provided keyword. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

curl --location 'https://api.x.com/2/communities/search?query=anime&amp;community.fields=access,created_at,description,id,join_policy,member_count,name' --header 'Authorization: $BEARER_TOKEN'

Sample Response

{
  "data": [
    {
      "id": "Q29tbXVuaXR5OjE3NTg3NDc4MTc2NDI3MDA5MjI=",
      "description": "Welcome to the Anime Community! Where anime fans gather to share their favorite shows and discuss everything anime-related.",
      "join_policy": "Open",
      "access": "Public",
      "member_count": 39915,
      "name": "Anime Community",
      "created_at": "2024-02-17T06:58:50.000Z"
    },
    {
      "id": "Q29tbXVuaXR5OjE1MDY3OTM5NTMxMDYwNDI4OTE=",
      "description": "Join and text about anime 🥰",
      "join_policy": "Open",
      "access": "Public",
      "member_count": 26019,
      "name": "Anime World 🌸",
      "created_at": "2022-03-24T00:44:07.000Z"
    },
    {
      "id": "Q29tbXVuaXR5OjE0OTY3NzYyMTU5Mzk1MzQ4NDk=",
      "description": "For all anime lovers and creators!",
      "join_policy": "Open",
      "access": "Public",
      "member_count": 5612,
      "name": "Anime",
      "created_at": "2022-02-24T09:17:13.000Z"
    }
  ],
  "meta": {
    "next_token": "7140dibdnow9c7btw481s8m561gat797rboud5r80xvzm"
  }
}

Complete field tables and additional examples are in the Data Dictionary Reference.

X API v2 data dictionary: Post, User, Space fields

Quick navigation

Quick navigation

Post (Tweet)

All Post fields

User

Space

List

Media

Poll

Place

Direct Message events

Community

​Quick navigation

​Quick navigation

​Post (Tweet)

​All Post fields

​User

​Space

​List

​Media

​Poll

​Place

​Direct Message events

​Community

Quick navigation

Quick navigation

Post (Tweet)

All Post fields

User

Space

List

Media

Poll

Place

Direct Message events

Community