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. | |
media_metadata | array | Contains metadata for media attachments of the Tweet. | Get additional metadata like the alt_text of a Tweet’s media attachment. |
$BEARER_TOKEN
with your own generated Bearer Token.
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" | |
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."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.x.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.x.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. |
$BEARER_TOKEN
with your own generated Bearer Token.
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. |
$BEARER_TOKEN
with your own generated Bearer Token.
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. |
$BEARER_TOKEN
with your generated Bearer Token.
?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"}] |
attachment.media_keys
expansion is required. Be sure to replace $BEARER_TOKEN
with your own generated Bearer Token.
?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"} |
attachments.poll_id
expansion is required. Be sure to replace $BEARER_TOKEN
with your own generated Bearer Token.
?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" |
geo.place_id
expansion is required. Be sure to replace $BEARER_TOKEN
with your own generated Bearer Token.
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. |
?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
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. |
$BEARER_TOKEN
with your own generated Bearer Token.
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.
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
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:
expansions
parameter with attachments.media_keys
as the value, and add this to the request.
?expansions=attachments.media_keys
Request:
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: