Consistency across the different Labs endpoints

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.

One of the main aspects of the Twitter Labs endpoints is consistency. This means that different features and behaviors of the API are uniform across similar endpoints.

You can expect the following elements to be the same across all Labs endpoints:

  • Path naming
    Path naming always includes the endpoint version, followed by the object, followed by query parameters.

    All endpoints therefore follow this structure: /version/object?param1=value&param2=value

    For example:
    /labs/1/tweets?ids=1092830408805400577&format=detailed
    /labs/1/users?ids=2244994945&format=compact

     

  • JSON Schema
    Responses to requests are defined using JSON Schema. This means that requests consistently return sets of objects as arrays, with each element having an ID. Requests do not return maps with IDs as keys.

  • Response object and parameters
    Every request returns the same response object:
    • id objects are always strings
    • parameters and response fields consistently use American-English spelling
    • fields are always returned, even if empty
    • fields are set to null if there is no value
    • the entities object only contains entities sourced from the Tweet text: this includes urls, hashtags, mentions and cashtags
    • all cards-related information, including the media_keys and poll_ids fields, are returned in the attachments object


Example response object (with the format parameter set to detailed):

{
  "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": 185,
        "reply_count": 0,
        "like_count": 1432,
        "quote_count": 29
      },
      "possibly_sensitive": false,
      "lang": "en",
      "source": "<a href=\"https://studio.twitter.com\" rel=\"nofollow\">Twitter Media Studio</a>",
      "format": "detailed"
    }
  ]
}

  • Authentication
    The Tweets and Users endpoints use OAuth 1.0a, also known as user context. This means that you have to provide your Twitter developer app’s API keys and tokens, as well as a set of access tokens that you generate for the user that you are making a request on behalf of. You can use the 3-legged OAuth flow to retrieve a set of access tokens from a user. You will also need to pass along a request signature with OAuth 1.0a.

    App-only authentication will be available soon for both GET /tweets and GET /users.

    More information on authentication can be found in our documentation on authentication.

  • Formats
    For endpoints where formats are relevant, such as GET /tweets and GET /users, formats are available as compact, default, and detailed. More details on formats can be found in our documentation on parameters.

  • Expansions
    Where appropriate, expansions are available for all nested id fields (for example, all fields named *_id, such as author_id). Expansions are also available for all fields that have an id that is not the top-level identifier of the current object (for example, the referenced_tweets object).

    Note that expansions can only be requested for the relevant format level (for example, you cannot request an expansion for the pinned_tweet_ids field if the format level is compact). 

Please report any inconsistencies that you notice, related to these fields.
 

Additional resources

  • Get started building with our quick start guides.
  • Check out our API reference to learn more about what’s available.
  • Give feedback on Twitter Developer Labs.
  • Tell us about your experience using the Twitter Developer Labs endpoints by filling out this survey.