Twitter API v2 data dictionary
Object Model
Tweet
Tweets are the basic building block of all things Twitter. The Tweet object has a long list of ‘root-level’ fields, such as id, text, and created_at. Tweet objects are also the ‘parent’ object to several child objects including user, media, poll, and place. Use the field parameter tweet.fields when requesting these root-level fields on the Tweet object.
The Tweet object that can be found and expanded in the user resource. Additional Tweets related to the requested Tweet can also be found and expanded in the Tweet resource. The object is available for expansion with ?expansions=pinned_tweet_id in the user resource or ?expansions=referenced_tweets.id in the Tweet resource to get the object with only default fields. Use the expansion with the field parameter: tweet.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 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. |
| 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. |
| 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. |
| 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. |
| 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. | Determine total impressions generated for the Tweet. |
| 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. | 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. |
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.
| 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" | |
| 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."entities": { <br/> "url": { <br/> "urls": [ <br/> { <br/> "start": 0, <br/> "end": 23, <br/> "url": "https://t.co/3ZX3TNiZCY", <br/> "expanded_url": "/content/developer-twitter/en/community", <br/> "display_url": "developer.twitter.com/en/community" <br/> } <br/> ] <br/> }, <br/> "description": { <br/> "urls": [ <br/> { <br/> "start": 0, <br/> "end": 23, <br/> "url": "https://t.co/3ZX3TNiZCY", <br/> "expanded_url": "/content/developer-twitter/en/community", <br/> "display_url": "developer.twitter.com/en/community" <br/> }, <br/> "hashtags": [ <br/> { <br/> "start": 23, <br/> "end": 30, <br/> "tag": "DevRel" <br/> }, <br/> { <br/> "start": 113, <br/> "end": 130, <br/> "tag": "BlackLivesMatter" <br/> }, <br/> "mentions": [ <br/> { <br/> "start": 0, <br/> "end": 10, <br/> "tag": "TwitterDev" <br/> }, <br/> "cashtags": [ <br/> { <br/> "start": 12, <br/> "end": 16, <br/> "tag": "twtr" <br/> } <br/> ] <br/> } <br/> } | 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. |
| 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" | |
| 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_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. |
| 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. |
| 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.
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.
| 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. |
| 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.
** 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.
| 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.
** 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.
| 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.
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.
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.
| 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.
Sample Response
Direct Message events
Direct Message (DM) conversations are made up of events. The Twitter 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 Twitter 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 * 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. |
| 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_id | 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
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.
| 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.
Sample Response
How to use fields and expansions
By default, the Twitter 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.
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.
-
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.
-
Build the
tweet.fieldsquery parameter with the above fields as its value using a comma-separated list:?tweet.fields=attachments,author_id,created_at,public_metrics -
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:
?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys&media.fields=public_metrics,duration_ms