> ## 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.
# Data Dictionary
> Definitive reference for every field, object, expansion, and metric returned by the X API v2. Covers Posts, Users, Media, Spaces, Lists, Polls, Places, Communities, Direct Messages, and all possible expansions.
The X API returns rich structured JSON. This dictionary documents every available field for each object type.
## Quick Navigation
* [Post (Tweet) fields](#post-tweet)
* [User fields](#user)
* [Space, List, Media, Poll, Place, Community, DM events](#space)
* [How to request fields & expansions](#how-to-use-fields-and-expansions)
* [Example payloads](#x-api-v2-example-payloads)
**Full detailed field tables → [Data Dictionary Reference](/x-api/fundamentals/data-dictionary/reference)**
## Quick navigation
| Object | Description | Fields parameter |
| :-------------------------- | :------------------------------ | :--------------- |
| [Post (Tweet)](#post-tweet) | Posts, replies, reposts, quotes | `tweet.fields` |
| [User](#user) | Account profiles and metadata | `user.fields` |
| [Space](#space) | Live audio conversations | `space.fields` |
| [List](#list) | Curated collections of accounts | `list.fields` |
| [Media](#media) | Images, videos, GIFs | `media.fields` |
| [Poll](#poll) | Poll questions and options | `poll.fields` |
| [Place](#place) | Location and geo data | `place.fields` |
Use [fields parameters](/x-api/fundamentals/fields) to request specific fields, and [expansions](/x-api/fundamentals/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](https://github.com/twitter/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. |
| **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](https://help.x.com/en/rules-and-policies/tweet-withheld-by-country). | |
| **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](/resources/fundamentals/rate-limits) endpoint. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication).
```bash theme={null}
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,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](/x-api/users/lookup/introduction) 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](https://help.x.com/en/rules-and-policies/tweet-withheld-by-country), if applicable. | |
**Retrieving a user object**
**Sample Request**
In the following request, we are requesting fields for the user on the [users lookup](/x-api/users/lookup/introduction) endpoint. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token).
```{ theme={null}
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**
```{ theme={null}
"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 & respond to the pandemic. \n\nWe're launching a free COVID-19 stream endpoint so qualified devs & 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](/x-api/spaces/lookup/introduction) 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](/x-api/spaces/lookup/introduction). Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token).
```bash theme={null}
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](https://help.x.com/en/using-twitter/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](/x-api/lists/list-lookup/introduction) endpoint. Replace `$BEARER_TOKEN` with your generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).
```bash theme={null}
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](/x-api/posts/lookup/introduction) 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](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).
```bash theme={null}
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](/x-api/posts/lookup/introduction) 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](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).
```bash theme={null}
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](/x-api/posts/lookup/introduction) 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](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).
```bash theme={null}
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](/x-api/direct-messages/lookup/introduction) endpoints, and a MessageCreate event is created when Direct Messages are successfully created with the [Manage Direct Messages](/x-api/direct-messages/lookup/introduction) 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](/x-api/fundamentals/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](/x-api/fundamentals/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`
```bash theme={null}
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](/resources/fundamentals/authentication#using-and-generating-an-app-only-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](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).
```bash theme={null}
curl --location 'https://api.x.com/2/communities/search?query=anime&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/fundamentals/data-dictionary/reference).**