Last week, the new Twitter API access tiers were finally announced. Unfortunately, some important details were left out from the announcement, leaving many developers confused and stressed out as the deprecation deadline is getting closer.

At Superface, we maintain social media integrations, including Twitter’s, and we’ve built an authorization library for Twitter API, so we’ve been closely observing the recent developments around Twitter API. (I’ve even made a site for that.)

In this article, I have collected observations and recommendations about Twitter’s new API. In summary:

• If possible, don’t migrate to the new plans yet
• You can use Twitter Login for free both with OAuth 2.0 and OAuth 1.0a
• You need to migrate your app to API v2
• You can post tweets with media
• You can still embed tweets
• If you need to do anything else than login users or post tweets, you'll have to pay a monthly fee (maybe even a large sum)
• Don’t rely on official support

Here’s a warning, though: Twitter is in constant flux, so any information in this article can become outdated at any time. I will do my best to keep it up to date – check the changelog and the original article for updates. If you notice any false or outdated information, please let me know.

What do we know from the announcement?

The changes were announced on the Twitter Dev account and the community forums. Here's what we can learn from these announcements:

• All existing API access tiers (Standard, Premium, Essential, and Elevated) are being replaced by the new Free and Basic tiers.
• Both tiers allow users to log in with Twitter, read the profile of an authorized user, and post tweets on behalf of users.
• Only the paid Basic tier provides read access to user profiles and tweets at a much lower rate than previous tiers (10,000 tweets per month, compared to 500,000 on Essential and 2 million on Elevated).
• The Basic tier costs $100 / month.
• The v1.1 API is being deprecated in favor of the v2 API (with an exception for media uploads, see below).
• The previous plans and legacy API will be deprecated by April 29th, 2023 at the latest – so technically the changes can happen any time sooner.
• The Twitter Ads API is unaffected by these changes.
• There are no special access plans for researchers and academics at this time.

Do I need to pay so the users of my app can log in with Twitter?

No, Twitter Login is available on the Free plan.

You can also read the information about a logged-in user through the GET /2/users/me endpoint. It is rate limited to 25 requests per 24 hours per user, so just make sure your integration code doesn’t read this endpoint too frequently (or fails gracefully when you hit the limit).

During my testing, I also frequently encountered a “Something went wrong” error on Twitter’s authorization page.

After a few retries, the authorization flow was successful. If your users encounter a similar issue, instruct them to just retry logging in a few times.

Do I need to use OAuth 2.0 for login?

No, both OAuth 1.0a and OAuth 2.0 (with app-only and user contexts) are supported on both access tiers.

You must use OAuth 1.0a if you want to publish tweets with images or videos. On the other hand, newer API features, like Bookmarks or Spaces are available only with OAuth 2.0. Check the Twitter v2 Authentication Mapping to see what features are supported in respective authentication contexts.

Do I need to migrate to the Twitter API v2?

Yes. According to the announcement, both Standard v1.1 and Premium v1.1 endpoints will be deprecated. The Basic tier is described as:

Rate limited access to suite of v2 endpoints

The only exceptions are media upload endpoints, which are not available in the v2 API.

Can I post tweets with media (images, GIFs, videos)?

Yes, that’s possible even on the Free plan, but you need to combine v2 API endpoints with v1.1 media upload endpoints. You must use OAuth 1.0a with read+write access, as media upload endpoints don’t support OAuth 2.0 access tokens.

Follow these steps to post a tweet with media attachments:

1. Upload media using the Upload media endpoints: POST media/upload for images or chunked upload endpoints for videos.
2. You will receive media_id for the uploaded objects.
3. Post a tweet using the POST /2/tweets endpoint and reference the uploaded media objects in a media property like this:

   {
     "text": "Tweet with media",
     "media": { "media_ids": ["1455952740635586573"] }
   }

Can I only post tweets with Free access?

Mostly, yes. It’s possible only to manage a user’s tweets (i.e., create, delete), upload media, and look up information about the authorized user.

If you hit a paid endpoint, you will get a non-descriptive error message like this:

{
  "title": "Forbidden",
  "type": "about:blank",
  "status": 403,
  "detail": "Forbidden"
}

Notably, you can’t read user’s tweets timeline or the mentions timeline. So if you are building an application that tracks users’ mentions (e.g., social media care or analytics, or a bot that replies to tweets), you will have to pay for Basic access.

I need to read more than 10,000 tweets per month, what should I do?

The next access tier after the Basic is Enterprise, which, according to the leaked sales documents, starts at $42,000 per month. You can apply through the Twitter Developer Portal.

No doubt there are other ways to get the data for cheaper or for free, but that’s outside the scope of this article.

Can I embed tweets?

Yes, Twitter for Websites features remain unaffected by these changes, including Embedded Tweets.

While there are reports of broken embeds, they are usually caused by suspended access to the Twitter API. For example, Substack reported issues with embeds, however, they use custom embeds unrelated to the official widgets. If you embed tweets on your own by fetching them from API, you will need to pay at least for the basic plan.

Should I migrate to the new plans now?

No. If you currently have Essential or Elevated access, I recommend stalling the migration to the Free and Basic plans at least until the limits enforcement stabilizes a bit. On the community forums, some users report losing access after purchasing the Basic access, probably because they were over the 10,000 tweets/month limit at the time of the purchase. Other users report issues with rate limits. These bugs seem to be symptoms of rushed development. We can hope that they will be fixed before the April 29th deadline.

Consider setting up a separate developer account with either Free or Basic access and test your application there first, before migrating your main account.

If you're using API v1.1, you should migrate your application to API v2. The new API is accessible both on the Essential and Elevated plans. Check Twitter’s migration guides.

And of course, be prepared that Twitter can suspend your application at any time, migrated or not.

Where can I get help with Twitter API?

If you run into issues with migration to the new access plans, don’t expect any help or refund from Twitter. As Ryan Barrett on the Twitter Developers forum points out, you can treat the Twitter API as effectively unmaintained.

Still, the Twitter Developers forum is probably the best place where you can get help from community volunteers and a good place to search for known issues.

If you’re migrating a Node.js application to API v2, take a look at our ready-made social media integrations, and our Twitter OAuth 2.0 strategy for Passport.js. We'll be happy to help you with Twitter API on Superface Discord or you can reach directly to us.

Your article is wrong or outdated / I still have questions

Please – let me know! Leave a comment or reach out to me on Mastodon or Discord.

I’m also sending out a monthly Superface Newsletter, so if you’d like to stay in touch and get more articles like this one with a mix of API and AI news, feel free to subscribe.