Formats: Labs v1 only

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

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.