Formats 

The endpoints we release in Labs will be previews and are likely to change before they are released broadly, so we encourage you to take that into consideration as you build. Before getting started, we encourage you to read more about Twitter Developer Labs.

Formats provide a standard way to specify the fields of data returned in an API response. Formats enable more or less detailed fields to be returned in the JSON response, while expansions provide a way to request additional referenced data in a single response.
 

Formats

Formats 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.
 

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
attachments X X X
withheld X X X


Formats with tweets

Response with compact format
{
  "data": [
    {
      "id": "1067094924124872705",
      "created_at": "2018-11-26T16:37:10.000Z",
      "text": "Just getting started with Twitter APIs? Find out what you need in order to build an app. Watch this video! https://t.co/Hg8nkfoizN",
      "author_id": "2244994945",
      "attachments": {
        "media_keys": [
          "13_1064638969197977600"
        ]
      },
      "format": "compact"
    }
  ]
}
Response with default format
{
  "data": [
    {
      "id": "1067094924124872705",
      "created_at": "2018-11-26T16:37:10.000Z",
      "text": "Just getting started with Twitter APIs? Find out what you need in order to build an app. Watch this video! https://t.co/Hg8nkfoizN",
      "author_id": "2244994945",
      "attachments": {
        "media_keys": [
          "13_1064638969197977600"
        ]
      },
      "entities": {
        "urls": [
          {
            "start": 107,
            "end": 130,
            "url": "https://t.co/Hg8nkfoizN"
          }
        ]
      },
      "format": "default"
    }
  ]
}
Response with detailed format
{
  "data": [
    {
      "id": "1067094924124872705",
      "created_at": "2018-11-26T16:37:10.000Z",
      "text": "Just getting started with Twitter APIs? Find out what you need in order to build an app. Watch this video! https://t.co/Hg8nkfoizN",
      "author_id": "2244994945",
      "attachments": {
        "media_keys": [
          "13_1064638969197977600"
        ]
      },
      "entities": {
        "urls": [
          {
            "start": 107,
            "end": 130,
            "url": "https://t.co/Hg8nkfoizN"
          }
        ]
      },
      "stats": {
        "retweet_count": 187,
        "reply_count": 57,
        "like_count": 1444
      },
      "possibly_sensitive": false,
      "lang": "en",
      "source": "<a href=\"https://studio.twitter.com\" rel=\"nofollow\">Twitter Media Studio</a>",
      "format": "detailed"
    }
  ]
}

 

Formats with users

Field Name Compact Default Detailed
id X X X
created_at X X X
name X X X
username X X X
location   X X
url   X X
description   X X
protected X X X
verified X X X
stats     X
entities   X X
profile_image_url X 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",
      "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": 502220,
        "following_count": 1474,
        "tweet_count": 3401,
        "listed_count": 1517
      },
      "format": "detailed"
    }
  ]
}

Additional resources