Announcing Early Access to the next generation of the Twitter API

tony · 2020-08-12T16:50:22.351Z

Announcing Early Access to the next generation of the Twitter API

Today we announced Early Access to the first endpoints of the new Twitter API!

We rebuilt the Twitter API from the ground up so that you are supported with a modern foundation. We’re just getting started and you can learn more about what we have planned in our “Guide to the future of the Twitter API”.

To help guide you through this forum post, we have organized it into the following table of contents.

What’s new and different?
New resources to support developers
The future of the Twitter API
Detailed technical information on each endpoint
Detailed technical information by product or feature

Here’s a recap of what’s included in today’s release, followed by more detail on each of these sections below:

What’s new and different?

A stronger foundation

With a new API foundation, you’re supported by a modern and sustainable API.
New functionality, more often:

This foundation makes it faster for us to deliver new functionality, including new endpoints, as our platform evolves to meet the needs of developers, researchers, businesses, and people using Twitter. You can find the new functionality, available today, organized below by product. New functionality and features include:

Endpoints to help you listen to and analyze the public conversation:
All endpoints we’re releasing today are available in our new Basic access level. This access level will provide standard access to Twitter API endpoints for free with an approved developer account.

Below you will find a breakdown of updates categorized by object and endpoint:
- Updates to the Tweet object
- Updates to the user object
  - Pinned Tweet in user objects
- Updates that apply to both the user object and Tweet object
  - Customize response data using the fields parameter
  - Simplified and updated JSON response objects
- Updates to recent search
  - 100% of matching Tweets in search queries
- Updates to filtered stream
  - Update streaming filters without disconnecting
  - Spam filtering
- Updates that apply to both filtered stream and recent search
  - More expressive query language for filtered stream and search
- Other updates
  - A new developer portal
  - An OpenAPI spec

New resources to support developers

New endpoints and new functionality call for new complementary resources to support developers in getting started with the new Twitter API. As a way to help you get started more easily and quickly with the common types of things developers have used the Twitter platform for, we’ve created a slew of new resources and have completely rethought the look and navigation of our documentation. These resources are listed below.

New documentation for the new Twitter API

With the release of our new endpoints, we have also completely rebuilt our developer documentation where you can find comprehensive information and developer resources to support your journey in building on our new endpoints. Among a new look and feel, you will also find more intuitive navigation to more quickly find the information you need, comprehensive API reference documentation, guides on integrating with each endpoint, migration guides, quick starts, sample apps, code snippets, and much more.
Simple tutorials for common use cases

As we initially announced, we’re releasing these endpoints at the Basic level for developers specifically looking to understand what’s happening in the public conversation. To that end, we have created tutorials to help you along the journey of getting started around five of the most common use cases developers use the Twitter API for.
- Stream Tweets in real-time
  Surface and stream Tweets and conversations as they happen in real-time
- Analyze past conversations
  Search for topics or keywords and analyze the related conversation.
- Explore a user’s Tweets
  Retrieve and explore a user’s timeline of Tweets and replies.
- Measure Tweet performance
  Build a simple tool to understand how users’ Tweets are performing in the world.
- Listen for important events
  Listen for events that matter to you so that you can trigger appropriate actions or notifications.
- Building an app to stream Tweets in real-time
  Learn how to build your own real-time Tweet streaming app using the filtered stream endpoints and Tweet annotations to listen for Tweets based on your own topics of interest.
Code resources

To help you get started quickly with these new endpoints and focus on building functionality that makes your app unique, we have created several code libraries, sample apps, and other code resources.
New API status page

To keep you informed of the operational status of these new endpoints, we have also created a new API status page. On this status page, you will find endpoints organized into functional groupings and labeled based on version. We encourage you to visit this page so that you can get notifications on products of interest.

The future of the Twitter API

As part of our initial announcement, we shared our roadmap along with our “Guide to the future of the Twitter API” to share what we’re exploring and planning. As you start developing with these first endpoints of the new Twitter API, know that we are not done yet. We are just getting started so expect to see major improvements on not only other endpoints that enable you to succeed with the Twitter platform, but also new access levels for different segments of developers. We value your feedback and encourage you to provide it to help shape the future.

With the release of these first endpoints, we are deprecating certain Labs endpoints due to their Twitter API v2 replacements in this release.

The following Labs v1 endpoints will be retired 60 days from today’s release:

Tweet metrics v1
Filtered stream v1
Sampled stream v1
Recent search v1

The following Labs v2 endpoint will be retired 90 days from today’s release:

Recent search v2

Getting started

To begin working with the new endpoints, you will need to create a Project and a new App in the new developer portal. You can also connect your new Project to existing Apps, if you would like.

Keep in mind that per our Developer Policy, you may only have one primary or production App per approved use case. If you create a new App to start using the new v2 API and have existing apps for the same use case, make sure you have no more than one development, staging, and production App (three total) for the same use case. See our Developer Policy for more information, including guidelines around additional apps for development or testing.

To get started with Early Access to the new Twitter API, visit the new developer portal. If you don’t yet have a developer account, apply to get started.

Share your feedback

If you have feedback, you can share your thoughts with us in our early access feedback channel by:

Voting or commenting on existing ideas. You can vote or comment on more than one idea. Feel free to share details about specific scenarios you have in mind by leaving a comment.
Creating a new idea. Your input is key in helping us explore ideas that are not part of our roadmap yet, and can help us prioritize our future eff yet, and can help us prioritize our future efforts.

Detailed technical information on each endpoint:

A note on using v2 endpoints

Tweet activity cap: Within the Basic access level there is an aggregate 500k Tweets/month activity cap on the recent search and filtered stream endpoints. In future releases, we’re planning to add options for elevated access: for example, free elevated access for academic research.

Tweet lookup:(2/tweets/:id and 2/tweets)

Return a variety of information about a single Tweet by id using a path parameter or multiple Tweets using a query parameter.

Request up to 100 Tweet IDs in a single request:

https://api.twitter.com/2/tweets?ids=1226967976454316033,1225917697675886593

Response (default):

{
  "data": [
    {
      "id": "1226967976454316033",
      "text": "Our global community of developers help drive the Twitter platform.\n\n🌍 🌏 🌎    https://t.co/WigZfR85FS"
    },
    {
      "id": "1225917697675886593",
      "text": "@TwitterEng *ahem* https://t.co/aroJHt2zQ1"
    }
  ]
}

Request a single Tweet:

https://api.twitter.com/2/tweets/1226967976454316033

Response (default):

{
  "data": {
    "id": "1226967976454316033",
    "text": "Our global community of developers help drive the Twitter platform.\n\n🌍 🌏 🌎       https://t.co/WigZfR85FS"
  }
}

User lookup: (2/users/:id and 2/users)

Return a variety of information about a single user by id using a path parameter or multiple users by the requested IDs or usernames as a query parameter.

Request:

You have four options:

https://api.twitter.com/2/users?ids=2244994945
https://api.twitter.com/2/users/2244994945
https://api.twitter.com/2/users/by?usernames=twitterdev
https://api.twitter.com/2/users/by/username/twitterdev

Response (default):

{
  "data": [
    {
      "id": "2244994945",
      "name": "Twitter Dev",
      "username": "TwitterDev"
    }
  ]
}

Request specifying more field parameters for specific metadata, this time for two users.

Request:

https://api.twitter.com/2/users/by?usernames=twitterdev,twitterapi&user.fields=created_at,location,description,pinned_tweet_id

Response:

{
  "data": [
    {
      "created_at": "2013-12-14T04:35:55.000Z",
      "description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API.\n\nNeed help? Visit https://t.co/DVDf7qKyS9",
      "id": "2244994945",
      "location": "127.0.0.1",
      "name": "Twitter Dev",
      "pinned_tweet_id": "1214281000932593667",
      "username": "TwitterDev"
    },
    {
      "created_at": "2007-05-23T06:01:13.000Z",
      "description": "The Real Twitter API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.",
      "id": "6253282",
      "location": "San Francisco, CA",
      "name": "Twitter API",
      "username": "TwitterAPI"
    }
  ]
}

Recent search: (2/tweets/search/recent)

Query the most recent seven days of Tweets, and receive full-fidelity responses. Use an expressive and powerful query language consisting of an expanded set of operators to find Tweets of interest.

Request:
https://api.twitter.com/2/tweets/search/recent?query=from:twitterdev

Response (default):

{
  "data": [
    {
      "id": "1275828087666679809",
      "text": "Learn how to create a sentiment score for your Tweets with Microsoft Azure, Python, and
    Twitter Developer Labs recent search functionality.\nhttps://t.co/IKM3zo6ngu"
    }
  ],
  "meta": {
    "newest_id": "1275828087666679809",
    "oldest_id": "1275828087666679809",
    "result_count": 1
  }
}

Filtered stream: (2/tweets/search/stream)

Filter the real-time stream of public Tweets by applying a set of rules. Use a more expressive query language, which includes an expanded set of operators, to filter and surface Tweets of interest.

Request:

https://api.twitter.com/2/tweets/search/stream?tweet.fields=text,created_at,entities&expansions=entities.mentions.username

Response:

{
  "data": {
    "created_at": "2020-02-10T20:35:36.000Z",
    "entities": {
     "urls": [
        {
          "start": 75,
          "end": 98,
          "url": "https://t.co/WigZfR85FS",
          "expanded_url": "https://twitter.com/tasiukwaplong/status/1226252279487049728",
          "display_url": "twitter.com/tasiukwaplong/…"
        }
      ]
    },
    "id": "1226967976454316033",
    "text": "Our global community of developers help drive the Twitter platform.\n\n🌍 🌏 🌎    https://t.co/WigZfR85FS"
  }
}

Sampled stream: (2/tweets/sample/stream)

Stream a sample of new Tweets as they are published, across ~1% of all public Tweets in real-time

Request:

https://api.twitter.com/2/tweets/sample/stream?tweet.fields=text,created_at,entities&expansions=entities.mentions.username

Response:

{
  "data": {
    "created_at": "2020-02-10T20:35:36.000Z",
    "entities": {
      "urls": [
        {
          "start": 75,
          "end": 98,
          "url": "https://t.co/WigZfR85FS",
          "expanded_url": "https://twitter.com/tasiukwaplong/status/1226252279487049728",
          "display_url": "twitter.com/tasiukwaplong/…"
        }
      ]
    },
    "id": "1226967976454316033",
    "text": "Our global community of developers help drive the Twitter platform.\n\n🌍 🌏 🌎       https://t.co/WigZfR85FS"
  }
}

Detailed technical information by product or feature:

Updates to the Tweet object

Tweet annotations: To make it easier to identify Tweets about specific topics and to discover Tweets on topics that may have been previously difficult to access, we have added new metadata elements to the Tweet object. These metadata elements are referred to as Tweet annotations and are derived from what is explicitly mentioned in the Tweet text itself.

Example request to the recent search endpoint using the context operator:
https://api.twitter.com/2/tweets/search/recent?tweet.fields=text,created_at,context_annotations,entities,public_metrics&query=context:66.961961812492148736

Example annotations metadata elements within the Tweet object:

  "context_annotations": [
        {
          "domain": {
          "id": "10",
          "name": "Person",
          "description": "Named people in the world like Nelson Mandela"
        },
        "entity": {
          "id": "871815676998033408",
          "name": "Ally Brooke",
          "description": "Ally Brooke"
        }
      },
      {
        "domain": {
          "id": "54",
          "name": "Musician",
          "description": "A musician in the world, like Adele or Bob Dylan"
        },
        "entity": {
          "id": "871815676998033408",
          "name": "Ally Brooke",
          "description": "Ally Brooke"
        }
      },
      {
        "domain": {
          "id": "55",
          "name": "Music Genre",
          "description": "A category for a musical style, like Pop, Rock, or Rap"
        },
        "entity": {
          "id": "810938279801470977",
          "name": "Pop",
          "description": "Pop"
        }
      }
    ],

New conversation id: As we also announced today, we are adding a long requested feature, the conversation id. The conversation id will appear on all Tweets, and on replies, will match the Tweet id of the parent most Tweet that started the conversation. This will help you more quickly identify Tweets that are part of a full conversation thread and linked to one another via replies so that you can easily rebuild Tweet conversations in your apps.
- Request:
  https://api.twitter.com/2/tweets/search/recent?query=cats&start_time=2020-04-16T17:27:00Z&end_time=2020-04-23T00:00:00Z&conversation_id=1227640996038684673
- Response:
```
"data": [
    {
      "author_id": "2244994945",
      "created_at": "2020-02-12T17:09:56.000Z",
      "id": "1227640996038684673",
      “conversation_id”: “1227640996038684673”,
      "lang": "en",
      "text": "Doctors: Googling stuff online does not make you a doctor\n\nDevelopers:
      https://t.co/mrju5ypPkb"
    }
]
```

Optional expansion to include referenced Tweets: With the new Twitter API, we have taken this opportunity to include quoted Tweets, replied-to Tweets and mentioned accounts within the same response when requesting a Tweet.

Request:
https://api.twitter.com/2/tweets/1237499623159353344?tweet.fields=referenced_tweets&expansions=referenced_tweets.id,entities.mentions.username

Response:

{
  "data": {
    "entities": {
      "mentions": [
        {
          "start": 12,
          "end": 20,
          "username": "brizzly"
        }
      ]
    },
    "id": "1237499623159353344",
    "referenced_tweets": [
      {
        "type": "quoted",
        "id": "1237456551604113409"
      }
    ],
    "text": "Our friends @Brizzly are back! We’re excited about their new Tweet compose &amp; auto-deletion tools. They even built...an edit feature!🙃 Check them out 👇 https://t.co/p7Hbt4qxPF"
  },
  "includes": {
    "users": [
      {
        "id": "56436449",
        "name": "Brizzly",
        "username": "brizzly"
      }
    ],
    "tweets": [
      {
        "id": "1237456551604113409",
        "text": "It's been a while but we have some news, today we're launching Brizzly+. Undo, Redo, Auto-deletion, and Custom Prompts for Twitter. https://t.co/1fvHJastyG"
      }
    ]
  }

Metrics data in Tweet objects: Public metrics data, and non-public metrics, are included in the Tweet lookup endpoint to more easily understand the performance of Tweets. Public metrics are metrics available for anyone to access on Twitter, while non-public metrics are only available for owned Tweets. Additionally, organic and promoted equivalents of these metrics are available for promoted Tweets from authorized accounts.
- tweet.fields=public_metrics returns:
  - retweet_count
  - quote_count
  - like_count
  - reply_count
- tweet.fields=non_public_metrics returns:
  - impression_count
  - url_link_clicks
  - user_profile_clicks
- expansions=attachments.media_keys&media.fields=public_metrics returns:
  - view_count
- expansions=attachments.media_keys&media.fields=non_public_metrics returns:
  - playback_0_count
  - playback_25_count
  - playback_50_count
  - playback_75_count
  - playback_100_count

Current poll results and poll options hydrated as part of Tweets: You can now include poll objects, if available, within the same response when requesting a Tweet.

Request:

https://api.twitter.com/2/tweets/1190944047713550336?tweet.fields=referenced_tweets&expansions=attachments.poll_ids

Response:

{
  "data": {
    "attachments": {
      "poll_ids": [
        "1190944047122173952"
      ]
    },
    "text": "Robot owl or real owl?",
    "id": "1190944047713550336",
    "referenced_tweets": [
      {
        "type": "replied_to",
        "id": "1190944045117214720"
      }
    ]
  },
  "includes": {
    "polls": [
      {
        "id": "1190944047122173952",
        "options": [
          {
            "position": 1,
            "label": "Robot owl",
            "votes": 1
          },
          {
            "position": 2,
            "label": "Real owl",
            "votes": 3
          }
        ]
      }
    ]
  }
}

Updates to the user object
- Pinned Tweet in user objects: An account’s pinned Tweet can be requested and returned within the same response when requesting a user resource.
Updates that apply to both the user object and Tweet object
- Customize response data using the fields parameter: Customize the data returned in your response according to only the data you need. By default, the id and text fields of a Tweet object, and the id, name, and username fields of a user object will be included in the response data. Example fields parameters for Tweets include created_at, lang, and expansions, to name a few. All available fields can be found in our documentation.
  - Request:
    
    https://api.twitter.com/2/tweets/1275828087666679809?tweet.fields=created_at,lang&expansions=author_id
  - Response:
```
{
    "data": {
    "author_id": "2244994945",
    "created_at": "2020-06-24T16:28:14.000Z",
    "id": "1275828087666679809",
    "lang": "en",
    "text": "Learn how to create a sentiment score for your Tweets with Microsoft Azure, Python, and Twitter Developer Labs recent search functionality.\nhttps://t.co/IKM3zo6ngu"
    },
    "includes": {
        "users": [
            {
            "id": "2244994945",
            "name": "Twitter Dev",
            "username": "TwitterDev"
            }
        ]
    }
}
```
- Simplified and updated JSON response objects: We’ve updated the Tweet and user response objects to help streamline your post processing needs and parse fields from these objects more quickly, easily and intuitively.
Updates to recent search
- 100% of matching Tweets in search queries: All matching Tweets will be returned in search queries as opposed to only a subset of matching Tweets returned in the v1.1 search/tweets endpoint
Updates to filtered stream
- Update streaming filters without disconnecting: Previously, in the v1.1 statuses/filter endpoint, you would first have to disconnect from your streaming and reconnect in order to see any rule changes. Now with filtered stream, you can make changes to your rules and see those changes take effect within seconds without having to disconnect from your streaming endpoint.
- Spam filtering: Filtered stream includes built-in spam filtering to help with the exclusion of high-confidence unwanted content. This will improve your interactions on our platform and reduce the irrelevant Tweets you receive.
Updates that apply to both filtered stream and recent search
- More expressive query language for filtered stream and search: Using a more expansive set of operators, you can more easily create rules and search queries that enable you to more easily surface Tweets based on your interests.
Other updates
- A new developer portal: Since we rolled out developer accounts in 2018, developers have primarily used our developer portal to access our self-serve APIs and to create and manage Apps. We’re redesigning the developer portal to better serve you and support the future of the Twitter API.
  
  With the new developer portal, we are introducing the concept of Projects. Projects allow you to organize your work based on how you intend to use the Twitter API, so you can effectively manage your access to the API. Each Project contains an App, with which you can generate the credentials required to use the Twitter API. You’ll need to create a Project to use v2 endpoints.
  
  New developer accounts will be guided through creating their first App and making their first request to the Twitter API. Developers with a developer account will be able to create a Project and new App with Basic access and see endpoints currently available in Early Access — along with detailed information, limits, and links to documentation for each endpoint.
- An OpenAPI spec: We’ve made this available to build new libraries and more transparently track new changes.

We’re excited to see what you build! If you have questions about v2 of the API as you get started, please use our new Twitter API v2 Early Access category on the developer forums.

tony · 2020-08-12T17:02:19.695Z

tony · 2020-08-12T17:03:16.170Z

tony · 2020-08-12T17:03:24.148Z

tony · 2020-08-12T17:03:41.986Z

LeBraat · 2021-11-15T18:53:51.237Z