Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.
Overview
Formats provide a standard way to specify the fields of data returned in an API response. By using the formats parameter, you can receive more or less detailed fields in your JSON response, while expansions provide a way to request additional referenced data in a single response.
The formats parameter is only available with v1 endpoints, and has been replaced with the fields parameter for all v2 endpoints.
Using formats
Formats is a paramater used to control the sets of fields returned for each request. Different formats provide different levels of detail. The levels of detail available are compact
, default
, and detailed
.
The format is specified with the format
request parameter. The format
parameter specifies the format for all resources in the response, unless a separate format for a resource is specified directly. For example, you may specify format=compact
to get minimal information for each resource in the response, but also specify user.format=detailed
to get all information about a user within the response. In this case, Tweets would return with minimal information, while users would return full information.
Available formats
compact
default
detailed
The compact
format returns the fewest fields in a response, while the detailed
format returns the most fields. If no format is specified, the default
format will be applied.
Tweet object formats
Field Name | Compact | Default | Detailed |
id |
X | X | X |
author_id |
X | X | X |
created_at |
X | X | X |
referenced_tweets |
X | X | X |
in_reply_to_user_id |
X | X | X |
text |
X | X | X |
geo |
X | X | |
entities |
X | X | |
stats |
X | ||
possibly_sensitive |
X | ||
source |
X | ||
lang |
X | ||
context_annotations | X | ||
attachments |
X | X | X |
withheld |
X | X | X |
Response with compact
format
{
"data": [
{
"id": "1189226081406083073",
"created_at": "2019-10-29T17:02:47.000Z",
"text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier.",
"author_id": "783214",
"in_reply_to_user_id": "783214",
"referenced_tweets": [
{
"type": "replied_to",
"id": "1151997885455581185"
}
],
"format": "compact"
}
]
}
Response with default
format
{
"data": [
{
"id": "1189226081406083073",
"created_at": "2019-10-29T17:02:47.000Z",
"text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier.",
"author_id": "783214",
"in_reply_to_user_id": "783214",
"referenced_tweets": [
{
"type": "replied_to",
"id": "1151997885455581185"
}
],
"format": "default"
}
]
}
Response with detailed
format
{
"data": [
{
"id": "1189226081406083073",
"created_at": "2019-10-29T17:02:47.000Z",
"text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier. See more details: https://t.co/eu1upmY4yo",
"author_id": "783214",
"in_reply_to_user_id": "783214",
"referenced_tweets": [
{
"type": "replied_to",
"id": "1151997885455581185"
}
],
"entities": {
"urls": [
{
"start": 113,
"end": 137,
"url": "https://t.co/eu1upmY4yo",
"expanded_url": "http://developer.twitter.com",
"display_url": "developer.twitter.com",
"status": 200,
"title": "Developers Tap into What’s Happening",
"description": "Discover the power of Twitter APIs"
}
],
"annotations": [
{
"start": 55,
"end": 61,
"probability": 0.9596,
"type": "Product",
"normalized_text": "Android"
}
]
},
"stats": {
"retweet_count": 341,
"reply_count": 372,
"like_count": 2773,
"quote_count": 70
},
"possibly_sensitive": false,
"lang": "en",
"source": "<a href=\"https://mobile.twitter.com\" rel=\"nofollow\">Twitter Web App</a>",
"context_annotations": [
{
"domain": {
"id": "45",
"name": "Brand Vertical",
"description": "Top level entities that describe a Brands industry"
},
"entity": {
"id": 781974596165640193,
"name": "Technology",
"description": "This entity includes conversation about Information Technology"
}
},
{
"domain": {
"id": "46",
"name": "Brand Category",
"description": "Categories within Brand Verticals that narrow down the scope of Brands"
},
"entity": {
"id": 10026820777,
"name": "Android",
"description": "Mobile operating system based on the Linux kernel."
}
}
],
"format": "detailed"
}
]
}
User object formats
Field Name | Compact | Default | Detailed |
id |
X | X | X |
created_at |
X | X | X |
name |
X | X | X |
username |
X | X | X |
protected |
X | X | X |
location |
X | X | |
url |
X | X | |
description |
X | X | |
verified |
X | X | X |
entities |
X | X | |
profile_image_url |
X | X | X |
stats |
X | ||
most_recent_tweet_id |
X | X | |
pinned_tweet_id |
X | X | |
withheld |
X | X | X |
Response with compact
format
{
"data": [
{
"id": "2244994945",
"created_at": "2013-12-14T04:35:55.000Z",
"name": "Twitter Dev",
"username": "TwitterDev",
"protected": false,
"verified": true,
"profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
"format": "compact"
}
]
}
Response with default
format
{
"data": [
{
"id": "2244994945",
"created_at": "2013-12-14T04:35:55.000Z",
"name": "Twitter Dev",
"username": "TwitterDev",
"protected": false,
"location": "Internet",
"url": "https://t.co/FGl7VOULyL",
"description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https://t.co/mGHnxZU8c1 ⌨️ #TapIntoTwitter",
"verified": true,
"entities": {
"url": {
"urls": [
{
"start": 0,
"end": 23,
"url": "https://t.co/FGl7VOULyL",
"expanded_url": "https://developer.twitter.com/",
"display_url": "developer.twitter.com"
}
]
},
"description": {
"urls": [
{
"start": 93,
"end": 116,
"url": "https://t.co/mGHnxZU8c1",
"expanded_url": "https://twittercommunity.com/",
"display_url": "twittercommunity.com"
}
],
"hashtags": [
{
"start": 120,
"end": 135,
"tag": "TapIntoTwitter"
}
]
}
},
"profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
"most_recent_tweet_id": "1158441822286303232",
"pinned_tweet_id": "1138505981460193280",
"format": "default"
}
]
}
Response with detailed
format
{
"data": [
{
"id": "2244994945",
"created_at": "2013-12-14T04:35:55.000Z",
"name": "Twitter Dev",
"username": "TwitterDev",
"protected": false,
"location": "Internet",
"url": "https://t.co/FGl7VOULyL",
"description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https://t.co/mGHnxZU8c1 ⌨️ #TapIntoTwitter",
"verified": true,
"entities": {
"url": {
"urls": [
{
"start": 0,
"end": 23,
"url": "https://t.co/FGl7VOULyL",
"expanded_url": "https://developer.twitter.com/",
"display_url": "developer.twitter.com"
}
]
},
"description": {
"urls": [
{
"start": 93,
"end": 116,
"url": "https://t.co/mGHnxZU8c1",
"expanded_url": "https://twittercommunity.com/",
"display_url": "twittercommunity.com"
}
],
"hashtags": [
{
"start": 120,
"end": 135,
"tag": "TapIntoTwitter"
}
]
}
},
"profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
"stats": {
"followers_count": 503253,
"following_count": 1474,
"tweet_count": 3419,
"listed_count": 1526
},
"most_recent_tweet_id": "1158441822286303232",
"pinned_tweet_id": "1138505981460193280",
"format": "detailed"
}
]
}
Additional resources
- Learn more about the new Developer Labs on the "About Labs" page.
- Learn more about What’s new.
- Give feedback on Twitter Developer Labs.
- Tell us about your experience using the Twitter Developer Labs endpoints by filling out this survey.