Skip to main content
The X API returns structured JSON objects representing posts, users, media, and more. This reference documents every field available for each object type.

​
Quick navigation

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

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.
Sample Response

​
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.   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.  
Sample Response

​
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. **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.
** Sample Response **

​
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. 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.
** Sample Response**

​
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. 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.

​
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. 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.
Sample Response

​
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. 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.
Sample Response

​
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. 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
Be sure to replace $BEARER_TOKEN with your own generated Bearer Token. Sample Response

​
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. 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.
Sample Response

​
How to use fields and expansions

By default, the X API v2 data objects include a small number of default fields when making a request without the use of the fields or expansions parameters. This guide will show you how to use the fields and expansions query parameters in your request to receive additional objects and fields in your response. In this guide, we will be requesting several fields in the following Tweet screenshot.   This image includes a screenshot of a Tweet posted by @X. You can see the Tweet text, username, published date and time, source, and public metrics. It also includes a video. As you can see in the screenshot, there are several visible pieces of information related to the Tweet, including the Tweet author, Tweet metrics, created timestamp, video, and video view count. There are also several pieces of data that are not visible within the screenshot, but are still available to request.  When making a request to the API, the default response is simple, containing only the default Tweet fields (id and text). You will also only receive the primary object that returns with the given endpoint that you are using, and not any of the associated data objects that might relate to the primary object. This simplicity, along with the fields and expansions parameters, enable you to request only those fields you require, depending on your use case.   

​
Requesting additional fields and objects.

First off, we will be requesting a Tweet object using a Tweet ID and the GET /tweets endpoint. Request:
Response:
The following step-by-step guide will show you how to retrieve the additional data we can see in the screenshot.
  1. Identify the additional fields that you would like to request by using our object model, or by reviewing the list of fields in the endpoints’ API reference pages. In this case, we will be requesting the following additional fields: attachments, author_id, created_at, public_metrics.
  2. Build the tweet.fields query parameter with the above fields as its value using a comma-separated list: ?tweet.fields=attachments,author_id,created_at,public_metrics
  3. Add the query parameter to the GET /tweets request that you made earlier.
Request: curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics' \ --header 'Authorization: Bearer $BEARER_TOKEN' Response:  
4. Next, we are going to request fields related to the video that was included in the Tweet. To do so, we will use the expansions parameter with attachments.media_keys as the value, and add this to the request. ?expansions=attachments.media_keys Request:  
Response, with the media object represented in the includes object:  
5. And finally, we are going to request the view count and duration of the video. These aren’t default fields so we have to specifically request them. Use the media.fields parameter with the comma-separated values, public_metrics and duration_ms in your request. ?media.fields=public_metrics,duration_ms Request:   curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys&media.fields=duration_ms,public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN' Response, which now includes all the data that can be seen in the Tweet screenshot:  
In total, we included the following parameters in this example:
  • ids=1260294888811347969
  • tweet.fields=attachments,author_id,created_at,public_metrics
  • expansions=attachments.media_keys
  • media.fields=public_metrics,duration_ms  
When tied together, here is what the full query string looks like:

​
X API v2 Example payloads

​
Tweet

​
Tweet reply

​
Extended Tweet

​
Tweet with media

​
Retweeted quote Tweet