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.

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 resource. Beyond that, the path can contain an ID that relates to the earlier resource, a selection verb which helps to determine which data to return (for example, search or sample), a delivery verb which helps to determine how the data will deliver (for example, stream), or another resource that is related to the first resource. Finally, you can append a query parameter to the end if the endpoint includes any query parameters. 

     /version/resource/id?param1=value&param2=value

     /version/resource/delivery/selection?param1=value&param2=value

    Here are some examples of what this might look like:

    /labs/2/tweets/1067094924124872705?expansions=attachments.media_keys&tweet.fields=author_id

    /labs/2/users/2244994945?user.fields=created_at,description

    /labs/2/tweets/stream/filter

    labs/2/tweets/search?query=snow

  • 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 empty or not returned if there is no value.
    • Tthe 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.

    Here is an example response object (with the tweet.fields parameter set to author_id,public_metrics,entities):
{
    "data": {
        "author_id": "2244994945",
        "entities": {
            "urls": [
                {
                    "start": 107,
                    "end": 130,
                    "url": "https://t.co/Hg8nkfoizN",
                    "expanded_url": "https://twitter.com/TwitterDev/status/1067094924124872705/video/1",
                    "display_url": "pic.twitter.com/Hg8nkfoizN"
                }
            ]
        },
        "id": "1067094924124872705",
        "public_metrics": {
            "retweet_count": 178,
            "reply_count": 56,
            "like_count": 1391,
            "quote_count": 31
        },
        "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"
    }
}

  • Authentication
    Most Labs endpoints require the use of OAuth 2.0 Bearer Token, also known as application-only authentication. This means that you will have to pass along a Bearer Token with your request to the endpoint to make a successful request. 

    For those endpoints that require you to be authorized to create, manipulate, or retrieve data on behalf of another user, you will have to use OAuth 1.0a 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 to make requests on behalf of them. You will also need to pass along a request signature with OAuth 1.0a User Context.

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

  • 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).

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

 


 

Additional resources