X API: A Developer's Guide to the X API v2
The X API (formerly the Twitter API) is X's official REST API. Version 2 lives at api.x.com/2 and covers posts, users, direct messages, lists, Spaces, media, and trends. Access starts at console.x.com and is pay-per-use: $0.015 per post created and $0.005 per post read. Posting needs a user access token. Adeli runs the X developer app for you and passes X's fees through at X's published rates.
The X API is X's official REST API for reading and writing X data: posts, users, direct messages, lists, Spaces, media, and trends. The current version, X API v2, lives at https://api.x.com/2/. It is pay-per-use: you buy credits in the X Developer Console and X deducts them per request. To post on someone's behalf you need a user access token, either from OAuth 2.0 with PKCE or from OAuth 1.0a.
Think of this guide as the map: each section gives the short answer and links to the post that covers it in full. Every X fact links to X's developer docs, checked on 2026-10-26.
What is the X API?
The X API is the programmatic interface to X, formerly the Twitter API. X describes v2 as the current version, with pay-per-use pricing, a JSON response format, and fields and expansions that let you request only the data you need. X calls v1.1 legacy with limited support.
The names you'll run into:
| Name you'll see | What it means now |
|---|---|
| X API v2 | The current API at api.x.com/2. Use it for new projects. |
| Twitter API | The old name for the same API. Endpoints still say tweets. |
| X API v1.1 | Legacy. Some media and specialized endpoints remain. |
| Enterprise APIs | Sales-led products with custom limits, some using Basic auth |
| X Ads API | A separate API at ads-api.x.com for advertising |
Source: About the X API.
What can you do with the X API?
The X API v2 reads and writes most of what a user sees on X. These are the resource groups most products use, with one representative endpoint each:
| Resource | Example endpoint | What it does |
|---|---|---|
| Posts | POST /2/tweets |
Create a post, reply, or thread |
| Post lookup | GET /2/tweets |
Fetch posts by ID |
| Timelines | GET /2/users/:id/tweets |
A user's posts |
| Search | GET /2/tweets/search/recent |
Posts from the last 7 days |
| Users | GET /2/users/me |
The authenticated user's profile |
| Media | POST /2/media/upload |
Upload images, GIFs, and video |
| Direct Messages | POST /2/dm_conversations |
Start a DM conversation |
| Analytics | GET /2/tweets/analytics |
Metrics for posts |
| Lists, Spaces, Trends | GET /2/trends/by/woeid/:id |
Curated lists, audio rooms, trending topics |
Endpoints from X's rate limits reference, which lists every v2 endpoint. X ships official Python and TypeScript SDKs, listed on its tools and libraries page.
The posting call has its own walkthrough: how to post a tweet with POST /2/tweets.
How much does the X API cost?
The X API is pay-per-use: writes are billed per request and reads per resource returned. There's no subscription and no minimum spend. The rates that matter for social products, from X's pricing page:
| Action | Price |
|---|---|
| Create a post | $0.015 per request |
| Create a post with a URL | $0.200 per request |
| Read a post | $0.005 per post returned |
| Read a user | $0.010 per user returned |
| Delete a post | $0.010 per request |
Pay-per-use plans are capped at 3 million post reads per billing cycle. Above that, X points you to Enterprise. Scenarios at SaaS and AI-agent scale are in our X API pricing breakdown.
How do I get X API access?
Sign in at console.x.com, accept the Developer Agreement, create an app, and buy credits. For new developers there are two X API access tiers:
| Access tier | Who it's for |
|---|---|
| Pay-per-use | The default self-serve plan since February 6, 2026 |
| Enterprise | High volume, custom rate limits, no published price |
The Free, Basic, and Pro tiers that older guides describe are closed to new developers or being moved to pay-per-use. Self-serve apps also have two posting rules Enterprise doesn't: replies only go through when the original author @mentioned or quoted the replying account, and a post can carry only one cashtag (Manage Posts guide). The full sign-up walkthrough is in X API access.
What is the X API console?
The X API console is the X Developer Console at console.x.com, where you manage everything about your developer app. In it you:
- Create apps and set their authentication type (OAuth 1.0a, OAuth 2.0, or both).
- Generate and regenerate keys and tokens. Each one is shown once, so store it right away.
- Buy credits and set a spending limit so a bug can't drain your balance.
- Watch usage and costs in real time.
- See each endpoint's rate limits, which X also lists in its docs.
Older tutorials send you to developer.twitter.com and its "Essential" and "Elevated" access levels. Those are gone.
What are X API keys and tokens?
An X developer app comes with up to five kinds of credentials, and each one does a different job. The one people search for, the "X API key", only identifies your app. It can't post.
| Credential | Also called | What it does |
|---|---|---|
| API Key and Secret | Consumer key and secret | Identifies your app; signs OAuth 1.0a requests; generates a Bearer Token |
| Bearer Token | App-only access token | Reads public data as your app. Read-only. |
| Access Token and Secret | OAuth 1.0a user tokens | Acts as one user. The console issues a pair for the app owner. |
| Client ID and Secret | OAuth 2.0 client credentials | Runs the OAuth 2.0 PKCE flow; the secret is for confidential clients only |
| OAuth 2.0 user access token | User token | Acts as a user with specific scopes; valid 2 hours |
Sources: API Key and Secret and OAuth 2.0 PKCE.
Which X API authentication should I use?
Use the Bearer Token for public reads and a user token for anything that acts as a user. X supports four methods, per its authentication overview:
| Method | Use it for | Can it post? |
|---|---|---|
| App-only (Bearer Token) | Public data: search, lookups, timelines | No |
| OAuth 2.0 Authorization Code with PKCE | Acting for other users with fine-grained scopes | Yes, with tweet.write |
| OAuth 1.0a User Context | Acting for users with signed requests | Yes |
| Basic authentication | Some Enterprise APIs | Not for v2 posting |
OAuth 2.0 is the direction X is heading. In September 2026 X added a token exchange that converts stored OAuth 1.0a user tokens into OAuth 2.0 tokens, and the guide says OAuth 1.0a "is being retired." Getting each token, refreshing it, and fixing the common errors is in our X API access token guide.
What are the X API rate limits?
Most X API v2 rate limits are per 15 minutes, and posting is capped at 100 per user per 15 minutes and 10,000 per app per 24 hours. User-token requests count against per-user limits; Bearer Token requests count against per-app limits.
| Endpoint | Per app | Per user |
|---|---|---|
POST /2/tweets |
10,000 / 24 hours | 100 / 15 min |
GET /2/tweets |
3,500 / 15 min | 5,000 / 15 min |
GET /2/tweets/search/recent |
450 / 15 min | 300 / 15 min |
POST /2/media/upload |
50,000 / 24 hours | 500 / 15 min |
Source: X API rate limits, checked 2026-10-26.
Going over returns 429 Too Many Requests. The x-rate-limit-reset header tells you when to retry. Marc Brooker, a Distinguished Engineer at AWS, wrote in Exponential Backoff And Jitter (March 4, 2015):
"The return on implementation complexity of using jittered backoff is huge, and it should be considered a standard approach for remote clients."
For an X integration, that means waiting until the reset time and adding a random delay, so a fleet of workers doesn't hit X at the same second. Per-endpoint tables, the headers, and retry code are in X API rate limits.
Every X API guide on this blog
| Question | Post |
|---|---|
| What does it cost? | X API pricing |
| How do I sign up and get keys? | X API access |
| Which token do I need, and how do I refresh it? | X API access token |
| How do I post, upload media, and thread? | Post a tweet with POST /2/tweets |
| How many requests can I make? | X API rate limits |
Should I build on the X API directly or use a unified API?
Build directly if you post from your own accounts on X alone; use a unified API if your customers connect their own accounts. X's per-request fees are the same either way. What changes is who owns the developer app, the OAuth flow, and the refresh job.
With Adeli's X API:
- No X developer app to run. Adeli maintains the X developer app, has passed X's review, and refreshes every connected account's tokens.
- One endpoint for every network. X posts go through the same
POST /api/v1/postscall as Instagram, TikTok, YouTube, Facebook, and Bluesky, with up to 4 images, 1 GIF, or 1 video, and threads of up to 24 more posts. - X's fees, passed through. X's API usage fees are passed through at X's published rates, and
GET /api/v1/usage/xreports the month's running total. - Priced per customer. An X account is included in the user profile, like every platform, so the bill tracks how many of your customers you serve. See Adeli's pricing.
If you're building posting into a marketing platform, an AI content tool, or vertical SaaS, the posting API covers X and every other live network with one API key.