Formats and expansions

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 and expansions 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


Projections with tweets

Response with compact format
{
  "data": [
    {
      "id": "1072921852610134016",
      "created_at": "2018-12-12T18:31:18.000Z",
      "text": "All app management is unifying on https://t.co/EfJLLFaLkk! Beginning today: \n\nhttps://t.co/PCwEGWityX\n> will be redirected to >\nhttps://t.co/c10Mtp2Fqz\n\nThere, you can manage all existing apps from https://t.co/1NDcn9C4M9 alongside all other dev resources. https://t.co/EjLFTr0KdW",
      "author_id": "6253282",
      "in_reply_to_user_id": null,
      "referenced_tweets": [],
      "attachments": {
        "media_keys": [],
        "poll_ids": []
      },
      "withheld": null,
      "format": "compact"
    }
  ],
  "includes": {
    "tweets": [],
    "users": [],
    "places": [],
    "media": [],
    "polls": []
  },
  "errors": []
}
Response with default format
{
  "data": [
    {
      "id": "1072921852610134016",
      "created_at": "2018-12-12T18:31:18.000Z",
      "text": "All app management is unifying on https://t.co/EfJLLFaLkk! Beginning today: \n\nhttps://t.co/PCwEGWityX\n> will be redirected to >\nhttps://t.co/c10Mtp2Fqz\n\nThere, you can manage all existing apps from https://t.co/1NDcn9C4M9 alongside all other dev resources. https://t.co/EjLFTr0KdW",
      "author_id": "6253282",
      "in_reply_to_user_id": null,
      "referenced_tweets": [],
      "attachments": {
        "media_keys": [],
        "poll_ids": []
      },
      "geo": null,
      "entities": {
        "urls": [
          {
            "start": 34,
            "end": 57,
            "url": "https://t.co/EfJLLFaLkk",
            "expanded_url": "https://developer.twitter.com",
            "display_url": "developer.twitter.com"
          },
          {
            "start": 78,
            "end": 101,
            "url": "https://t.co/PCwEGWityX",
            "expanded_url": "https://Apps.twitter.com",
            "display_url": "Apps.twitter.com"
          },
          {
            "start": 134,
            "end": 157,
            "url": "https://t.co/c10Mtp2Fqz",
            "expanded_url": "https://Developer.twitter.com",
            "display_url": "Developer.twitter.com"
          },
          {
            "start": 204,
            "end": 227,
            "url": "https://t.co/1NDcn9C4M9",
            "expanded_url": "https://apps.twitter.com",
            "display_url": "apps.twitter.com"
          },
          {
            "start": 263,
            "end": 286,
            "url": "https://t.co/EjLFTr0KdW",
            "expanded_url": "https://twittercommunity.com/t/beginning-today-developer-twitter-com-will-replace-apps-twitter-com-for-all-app-management/118280",
            "display_url": "twittercommunity.com/t/beginning-to…"
          }
        ],
        "hashtags": [],
        "mentions": [],
        "cashtags": []
      },
      "withheld": null,
      "format": "default"
    }
  ],
  "includes": {
    "tweets": [],
    "users": [],
    "places": [],
    "media": [],
    "polls": []
  },
  "errors": []
}
Response with detailed format
{
  "data": [
    {
      "id": "1072921852610134016",
      "created_at": "2018-12-12T18:31:18.000Z",
      "text": "All app management is unifying on https://t.co/EfJLLFaLkk! Beginning today: \n\nhttps://t.co/PCwEGWityX\n> will be redirected to >\nhttps://t.co/c10Mtp2Fqz\n\nThere, you can manage all existing apps from https://t.co/1NDcn9C4M9 alongside all other dev resources. https://t.co/EjLFTr0KdW",
      "author_id": "6253282",
      "in_reply_to_user_id": null,
      "referenced_tweets": [],
      "attachments": {
        "media_keys": [],
        "poll_ids": []
      },
      "geo": null,
      "entities": {
        "urls": [
          {
            "start": 34,
            "end": 57,
            "url": "https://t.co/EfJLLFaLkk",
            "expanded_url": "https://developer.twitter.com",
            "display_url": "developer.twitter.com"
          },
          {
            "start": 78,
            "end": 101,
            "url": "https://t.co/PCwEGWityX",
            "expanded_url": "https://Apps.twitter.com",
            "display_url": "Apps.twitter.com"
          },
          {
            "start": 134,
            "end": 157,
            "url": "https://t.co/c10Mtp2Fqz",
            "expanded_url": "https://Developer.twitter.com",
            "display_url": "Developer.twitter.com"
          },
          {
            "start": 204,
            "end": 227,
            "url": "https://t.co/1NDcn9C4M9",
            "expanded_url": "https://apps.twitter.com",
            "display_url": "apps.twitter.com"
          },
          {
            "start": 263,
            "end": 286,
            "url": "https://t.co/EjLFTr0KdW",
            "expanded_url": "https://twittercommunity.com/t/beginning-today-developer-twitter-com-will-replace-apps-twitter-com-for-all-app-management/118280",
            "display_url": "twittercommunity.com/t/beginning-to…"
          }
        ],
        "hashtags": [],
        "mentions": [],
        "cashtags": []
      },
      "stats": {
        "retweet_count": 143,
        "reply_count": 44,
        "like_count": 244
      },
      "possibly_sensitive": false,
      "lang": "en",
      "source": "<a href=\"http://twitter.com\" rel=\"nofollow\">Twitter Web Client</a>",
      "withheld": null,
      "format": "detailed"
    }
  ],
  "includes": {
    "tweets": [],
    "users": [],
    "places": [],
    "media": [],
    "polls": []
  },
  "errors": []
}


Example request:

curl https://api.twitter.com/labs/1/users?usernames=twitterdev&format=compact

Projections 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,
      "withheld": null,
      "verified": true,
      "profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
      "format": "compact"
    }
  ],
  "includes": {
    "tweets": [],
    "users": [],
    "places": [],
    "media": [],
    "polls": []
  },
  "errors": []
}
Response with default format
{
  "data": [
    {
      "id": "2244994945",
      "created_at": "2013-12-14T04:35:55.000Z",
      "name": "Twitter Dev",
      "username": "TwitterDev",
      "protected": false,
      "withheld": null,
      "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"
            }
          ],
          "mentions": [],
          "cashtags": []
        }
      },
      "profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
      "format": "default"
    }
  ],
  "includes": {
    "tweets": [],
    "users": [],
    "places": [],
    "media": [],
    "polls": []
  },
  "errors": []
}
Response with detailed format
{
  "data": [
    {
      "id": "2244994945",
      "created_at": "2013-12-14T04:35:55.000Z",
      "name": "Twitter Dev",
      "username": "TwitterDev",
      "protected": false,
      "withheld": null,
      "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"
            }
          ],
          "mentions": [],
          "cashtags": []
        }
      },
      "profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
      "stats": {
        "followers_count": 501974,
        "following_count": 1473,
        "tweet_count": 3389,
        "listed_count": 1506
      },
      "format": "detailed"
    }
  ],
  "includes": {
    "tweets": [],
    "users": [],
    "places": [],
    "media": [],
    "polls": []
  },
  "errors": []
}


Expansions

Expansions enable requests to expand the complementary objects referenced in API responses. Expanding an object returns all of its fields and embeds it in a single response. Complementary objects are referenced by ID. Many ID fields within the main data payload are eligible for expansion. A request can specify which IDs should be expanded by specifying a comma-separated list of nouns and fields within the expansions request parameter.

Available expansions

  • author_id
  • referenced_tweets.id
  • in_reply_to_user_id 
  • attachments.media_keys
  • attachments.poll_ids
  • geo.place_id


Example request:
 

curl https://api.twitter.com/labs/1/tweets?ids=1117897901500297217&expansions=author_id,referenced_tweets.id,in_reply_to_user_id,attachments.poll_ids&format=compact


Example response:
 

{
  "data": [
    {
      "id": "1117897901500297217",
      "created_at": "2019-04-15T21:10:03.000Z",
      "text": "What is your favorite weekday of the week?",
      "author_id": "1021521993789624321",
      "in_reply_to_user_id": "1021521993789624321",
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1115482402795610112"
        }
      ],
      "attachments": {
        "media_keys": [],
        "poll_ids": [
          "1117897901294772224"
        ]
      },
      "withheld": null,
      "format": "compact"
    }
  ],
  "includes": {
    "tweets": [
      {
        "id": "1115482402795610112",
        "created_at": "2019-04-09T05:11:44.000Z",
        "text": "Good night again",
        "author_id": "1021521993789624321",
        "in_reply_to_user_id": null,
        "referenced_tweets": [],
        "attachments": {
          "media_keys": [],
          "poll_ids": []
        },
        "withheld": null,
        "format": "compact"
      }
    ],
    "users": [
      {
        "id": "1021521993789624321",
        "created_at": "2018-07-23T22:26:37.000Z",
        "name": "Tony Vu",
        "username": "sactocommuter",
        "protected": false,
        "withheld": null,
        "verified": false,
        "profile_image_url": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png",
        "format": "compact"
      }
    ],
    "places": [],
    "media": [],
    "polls": [
      {
        "id": "1117897901294772224",
        "options": [
          {
            "position": 1,
            "label": "Monday",
            "votes": 0
          },
          {
            "position": 2,
            "label": "Tuesday",
            "votes": 0
          },
          {
            "position": 3,
            "label": "Thursday",
            "votes": 0
          },
          {
            "position": 4,
            "label": "Friday",
            "votes": 0
          }
        ],
        "voting_status": "closed",
        "end_datetime": "2019-04-16T21:10:03.000Z",
        "duration_minutes": 1440
      }
    ]
  },
  "errors": []
}


Expansions with /tweets
 

No expansions tweet.author_id tweet.referenced_tweets.id

{
  "data": [
    {
      "id": "1117897901500297217",
      "created_at": "2019-04-15T21:10:03.000Z",
      "text": "What is your favorite weekday of the week?",
      "author_id": "1021521993789624321",
      "in_reply_to_user_id": "1021521993789624321",
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1115482402795610112"
        }
      ],
      "attachments": {
        "media_keys": [],
        "poll_ids": [
          "1117897901294772224"
        ]
      },
      "withheld": null,
      "format": "compact"
    }
  ],
  "includes": {
    "tweets": [],
    "users": [],
    "places": [],
    "media": [],
    "polls": []
  },
  "errors": []
}





  "includes": {
    "users": [
      {
        "id": "6253282",
        "created_at": "2007-05-23T06:01:13.000Z",
        "name": "Twitter API",
        "username": "TwitterAPI",
        "protected": false,
        "withheld": null,
        "verified": true,
        "profile_image_url": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg",
        "format": "compact"
      }
    ],








"includes": {
  "tweets": [
    {
      "id": "1115482402795610112",
      "created_at": "2019-04-09T05:11:44.000Z",
      "text": "Good night again",
      "author_id": "1021521993789624321",
      "in_reply_to_user_id": null,
      "referenced_tweets": [],
      "attachments": {
        "media_keys": [],
        "poll_ids": []
      },
      "withheld": null,
      "format": "compact"
    }
  ],









tweet.in_reply_to_user_id tweet.attachments.media_keys tweet.attachments.poll_ids
 "includes": {
    "users": [
      {
        "id": "6253282",
        "created_at": "2007-05-23T06:01:13.000Z",
        "name": "Twitter API",
        "username": "TwitterAPI",
        "protected": false,
        "withheld": null,
        "verified": true,
        "profile_image_url": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg",
        "format": "compact"
      }
    ],










"media": [
  {
    "media_key": "3_1126678972945670145",
    "height": 43,
    "width": 89,
    "url": "https://pbs.twimg.com/media/D6LEjnZUIAE7yDQ.png",
    "type": "photo"
  }
],








"polls": [
  {
    "id": "1117897901294772224",
    "options": [
      {
        "position": 1,
        "label": "Monday",
        "votes": 0
      },
      {
        "position": 2,
        "label": "Tuesday",
        "votes": 0
      },
      {
        "position": 3,
        "label": "Thursday",
        "votes": 0
      },
      {
        "position": 4,
        "label": "Friday",
        "votes": 0
      }
    ],
    "voting_status": "closed",
    "end_datetime": "2019-04-16T21:10:03.000Z",
    "duration_minutes": 1440
  }






tweet.geo.place_id    

"places": [
   {
     "id": "5a110d312052166f",
     "name": "San Francisco",
     "country_code": "US",
     "format": "compact"
   }
 ]






   


Next steps