NewAnswers MCP: one question, one checked answer for your agent.See how it works

Guides

X API (formerly the Twitter API): pricing, API keys, endpoints, MCP and scraping rules

By , founder of HyperresearchPublished

The X API (formerly the Twitter API) is X’s official interface for reading and publishing posts, users, lists, DMs and more, at https://api.x.com/2. Since February 6, 2026 it is sold pay-per-use: you buy prepaid credits in the Developer Console at console.x.com and pay per item, $0.005 per post read, $0.010 per user read and $0.015 per post you create ($0.20 if the post contains a URL), and X’s pricing page lists no free plan. To get a key, sign in at console.x.com with an X account, accept the Developer Agreement, create an app, and copy the API key and secret, bearer token and OAuth 2.0 client ID and secret, which are shown once.

Every price, limit and step below was read from X’s own documentation, developer site and terms on 2026-11-15. X says its prices can change, and the Developer Console shows the current rates.

X API pricing in November 2026: pay-per-use credits

X API v2 is sold on credits with no subscription. The pricing page says you buy credits up front, each endpoint has its own rate, and there are no contracts or minimum spend. Reads are charged per resource returned, so a search that returns 100 posts is 100 post reads. Writes are charged per request.

Read Price per resource
Posts: Read $0.005
User: Read $0.010
Following/Followers: Read $0.010
DM Event: Read $0.010
List, Space, Community, Note: Read $0.005
Like, Mute, Block: Read $0.001
Owned Reads (your own posts, mentions, bookmarks, followers, likes, lists) $0.001
Write or request Price per request
Post: Create $0.015
Post: Create with a URL $0.200
Post: Create, summoned reply (you were mentioned or quoted) $0.010
DM Interaction: Create $0.015
User Interaction: Create $0.015
Interaction: Delete $0.010
Article: Draft, Article: Publish $0.010 each
Counts: Recent / Counts: All $0.005 / $0.010
Trends $0.010
Bookmark, Media Metadata, Content: Manage $0.005

The rules that change the bill:

  • Deduplication. The same resource fetched twice in one UTC day is charged once. The window resets at midnight UTC, and X calls it a soft guarantee.
  • Failed requests are free. X’s post cap page says only successful responses that return data are billed.
  • A monthly cap. X’s pricing docs cap pay-per-use at 3 million post reads per monthly billing cycle; past that, X points you to an Enterprise plan. At $0.005 a read, the cap is $15,000 of post reads a month.
  • Owned Reads. Twelve endpoints, such as GET /2/users/{id}/tweets and /bookmarks, cost $0.001 per resource when {id} is the authenticated user who owns the app.
  • Running out. Requests fail until you add credits. The balance can go slightly negative, and then requests are blocked until you cover it. A per-cycle spending limit and auto-recharge are set in the console; auto-recharge fires at most once every 5 minutes.
  • Webhook events from the X Activity API are billed per event, for example $0.005 per post.create and $0.010 per dm.received; deletes and sent-message events are not billed.

The developer.x.com pricing section lists the same per-item rates and calls the subscriptions the “Old Model”, with fixed monthly fees of $200 or $5,000.

What is free on the X API

X’s pricing page lists no free plan. The February 6, 2026 launch note gave recently active users of the legacy Free tier a one-time $10 voucher. What you can still get without paying:

  • $20 in credits after your first credit purchase with the first eligible card on a new account, and a match of your first auto-recharge up to $50. Both are one-time, granted automatically, spent before purchased credits, and expire 3 months after they are granted. X announced them on October 2, 2026 and since October 13, 2026 adding a card alone no longer earns the $20. Details are on the free credits page.
  • Public Utility credits for public-good apps. You request them from a live Developer Exhibit listing and the X Dev Platform team decides.
  • xAI API credits of 10% to 20% back once you spend $200 or more in a billing cycle (10% from $200, 15% from $500, 20% from $1,000), after you link an xAI team. They pay for xAI’s Grok API, not for X API calls.
  • The X API Playground (xdevplatform/playground), a local server that mimics v2 endpoints with mock data, so you can build without spending credits.
  • The docs MCP server at https://docs.x.com/mcp, which searches X’s documentation and needs no key.

Worked monthly cost example

A small brand-monitoring app that searches recent posts, looks up the authors and posts a few updates:

Item Volume in 30 days Rate Cost
Recent search, new posts returned 500 a day = 15,000 $0.005 $75.00
User lookups, unique authors 2,000 $0.010 $20.00
Your posts without a link 60 $0.015 $0.90
Your posts with a link 30 $0.200 $6.00
Total $101.90

Re-reading the same posts on the same UTC day adds nothing, and searches that return nothing cost nothing. The $101.90 is under the $200 a month the old Basic plan charged, and under the $200 threshold where xAI credits start. The same arithmetic shows where pay-per-use gets expensive: links cost more than 13 times a plain post, and reading 1 million posts is $5,000.

X API price history with dates

Date Change
Oct 30, 2024 Basic subscription rose from $100 to $200 a month (TechCrunch); Pro was $5,000 a month
Aug 22, 2025 Like and follow endpoints removed from the Free tier
Oct 20, 2025 Closed pilot of pay-per-use: $0.005 per post read, $0.01 per user read
Feb 6, 2026 Pay-per-use launched with console.x.com, the XDK SDKs and an MCP server; Basic and Pro kept for existing subscribers, who could opt in
Feb 23, 2026 Programmatic replies allowed only when the original author summoned you
Apr 20, 2026 Owned Reads at $0.001; Post: Create to $0.015; posts with a URL to $0.20; following, likes and quote-posts removed from all self-serve tiers
May 4, 2026 Search moved to a new index; keyword search no longer returns reposts
Jun 30, 2026 Hosted X MCP server reported (TechCrunch)
Oct 2, 2026 $20 card credit and auto-recharge match up to $50 announced
Nov 10, 2026 Read-only mode for the X MCP (?read_only=true)

All dates except the two TechCrunch rows come from X’s changelog. Guides that still show a free tier with 500 posts a month, a $100 Basic plan, or a pay-per-use beta describe the API before 2026.

How to get an X API key and bearer token

X’s Getting Access page lays out three steps:

  1. Go to console.x.com and sign in with your X account.
  2. Accept the Developer Agreement and Policy, and describe how you will use the API.
  3. Click New App, enter a name, description and use case, and generate credentials.

The console then shows these credentials once. Copy them into a password manager straight away; losing one means regenerating it, which invalidates the old value.

Credential Use
API Key and Secret (consumer key) Identify the app; sign OAuth 1.0a requests; mint a bearer token
Bearer Token App-only access to public data: search, post and user lookup
Access Token and Secret Act as your own account (OAuth 1.0a): posting from your bot
Client ID and Secret OAuth 2.0 with PKCE, to act for other users with scopes

To make paid calls you need credits on the account, and X’s pay-per-use agreement requires a verified phone number to buy them. If a call returns client-not-enrolled, X’s MCP troubleshooting table says to move the app to the Pay-per-use package and Production environment in the console.

You can also mint the bearer token from the key and secret. Only one bearer token exists per app at a time, so cache it:

Terminal window
curl -u "$X_API_KEY:$X_API_SECRET" \
--data "grant_type=client_credentials" \
https://api.x.com/oauth2/token

Then test it with a lookup of X’s own developer account, which costs one user read ($0.010):

Terminal window
export X_BEARER_TOKEN=YOUR_BEARER_TOKEN
curl "https://api.x.com/2/users/by/username/xdevelopers" \
-H "Authorization: Bearer $X_BEARER_TOKEN"

Authentication: bearer token, OAuth 2.0 PKCE and OAuth 1.0a

Method What it can do Token life Typical use
App-only bearer token Read public data Until invalidated Search, lookups, analytics
OAuth 2.0 Authorization Code with PKCE Act for a user within granted scopes Access token 2 hours; refresh token single-use, about 6 months, with offline.access Apps other people sign in to
OAuth 1.0a user context Act for a user with the app’s permission level Does not expire Your own bot; older code

OAuth 2.0 authorizes at https://x.com/i/oauth2/authorize and exchanges tokens at https://api.x.com/2/oauth2/token, with S256 code challenges. Scopes include tweet.read, tweet.write, users.read, bookmark.write, dm.read and offline.access. Since September 2026 X also lets apps swap stored OAuth 1.0a user tokens for OAuth 2.0 tokens without asking users again (token exchange).

X API v2 endpoints, auth and rate limits

Limits are per 15 minutes unless noted, from X’s rate limits page. Per-app limits apply to bearer tokens; per-user limits apply to user tokens. Rate limits are separate from billing: staying under them does not make calls free.

Endpoint Returns Auth Per app Per user Billed as
GET /2/tweets/search/recent Posts from the last 7 days, 10 to 100 a page, 512-character query Bearer or user 450 300 Post read each
GET /2/tweets/search/all Posts back to March 2006, up to 500 a page, 1,024-character query Bearer or user 1/sec, 300 1/sec Post read each
GET /2/tweets/:id One post Bearer or user 450 900 Post read
GET /2/tweets?ids= Up to 100 posts by ID Bearer or user 3,500 5,000 Post read each
GET /2/users/by/username/:username One user profile Bearer or user 300 900 User read
GET /2/users/:id/tweets A user’s posts (timeline) Bearer or user 10,000 900 Post read each; $0.001 if your own
GET /2/users/:id/mentions Posts mentioning a user Bearer or user 450 300 Post read each; $0.001 if your own
GET /2/users/:id/timelines/reverse_chronological Your home timeline User only n/a 180 Post read each
POST /2/tweets Creates a post or summoned reply User only 10,000/24 hrs 100 $0.015, $0.20 with URL, $0.010 summoned
GET /2/tweets/counts/recent Post counts over time, 7 days Bearer 300 n/a $0.005 per request
GET /2/trends/by/woeid/:id Trends for a location Bearer 75 n/a $0.010 per request
GET /2/usage/tweets Your daily post consumption Bearer 50 n/a Not in the price list

Full-archive search is open to pay-per-use and Enterprise accounts. Keyword searches have not returned reposts since the May 4, 2026 index change, and min_likes:, min_replies: and min_reposts: work again. The rate limit page still lists like and follow endpoints, but X removed following, likes and quote-posts from all self-serve tiers on April 20, 2026, so they are left out here. Each response carries x-rate-limit-limit, x-rate-limit-remaining and x-rate-limit-reset (a Unix time).

Python example with requests

This searches the last seven days with a bearer token, follows next_token pages, waits out a 429 until x-rate-limit-reset, and prints the credit cost. A 200-post run costs about $1.00.

import os
import time
import requests
BEARER_TOKEN = os.environ["X_BEARER_TOKEN"]
BASE_URL = "https://api.x.com/2"
POST_READ_USD = 0.005 # Posts: Read, per post returned (docs.x.com pricing, Nov 2026)
def x_get(path, params=None):
"""GET an X API v2 endpoint with app-only auth; wait out a 429 once."""
headers = {"Authorization": f"Bearer {BEARER_TOKEN}"}
for _ in range(2):
resp = requests.get(f"{BASE_URL}{path}", headers=headers, params=params, timeout=30)
if resp.status_code == 429:
reset = int(resp.headers.get("x-rate-limit-reset", time.time() + 60))
time.sleep(max(reset - time.time(), 1) + 1)
continue
if resp.status_code != 200:
# Errors are application/problem+json: title, detail, type, status
raise RuntimeError(f"X API {resp.status_code}: {resp.text[:300]}")
return resp.json()
raise RuntimeError("Still rate limited after waiting for the reset")
def search_recent(query, max_posts=200):
"""Search the last 7 days; every post returned is billed as one Post read."""
params = {
"query": query,
"max_results": 100, # 10 to 100 per page
"tweet.fields": "created_at,author_id,public_metrics,lang",
}
posts = []
while len(posts) < max_posts:
page = x_get("/tweets/search/recent", params)
posts.extend(page.get("data", []))
next_token = page.get("meta", {}).get("next_token")
if not next_token:
break
params["next_token"] = next_token
return posts[:max_posts]
if __name__ == "__main__":
found = search_recent('"model context protocol" lang:en -is:retweet', max_posts=200)
print(f"{len(found)} posts, about ${len(found) * POST_READ_USD:.2f} in credits")
for post in found[:5]:
print(post["created_at"], post["id"], post["text"][:80].replace("\n", " "))

Set max_posts before you run a broad query: the cost is the number of posts returned, not the number of requests.

Python example with the official XDK

X’s official Python SDK is the XDK (pip install xdk, version 0.10.6 on PyPI, July 2026; source at xdevplatform/xdk-python). It is generated from X’s OpenAPI spec, supports bearer, OAuth 2.0 PKCE and OAuth 1.0a, and pages through results for you. A TypeScript version is npm install @xdevplatform/xdk.

import os
from xdk import Client
client = Client(bearer_token=os.environ["X_BEARER_TOKEN"])
# One user by handle (billed as one User read)
user = client.users.get_by_username(username="XDevelopers")
print(user.data)
# Recent search: search_recent returns an iterator of pages
for page in client.posts.search_recent(query="from:XDevelopers", max_results=10):
for post in page.data or []:
print(post.id, post.text[:80])
break # stop after the first page to cap the cost at 10 Post reads

Posting needs user context. With your own account’s access token and secret (OAuth 1.0a):

import os
from xdk import Client
from xdk.oauth1_auth import OAuth1
oauth1 = OAuth1(
api_key=os.environ["X_API_KEY"],
api_secret=os.environ["X_API_SECRET"],
callback="http://localhost:8080/callback",
access_token=os.environ["X_ACCESS_TOKEN"],
access_token_secret=os.environ["X_ACCESS_TOKEN_SECRET"],
)
client = Client(auth=oauth1)
# $0.015 for a plain post; $0.20 if the text contains a URL
response = client.posts.create(body={"text": "Hello from the X API"})
print(response.data)

A reply through POST /2/tweets is accepted only when the author of the post you reply to mentioned or quoted your account first. X added that rule on February 23, 2026 for all self-serve access.

X API errors and fixes

X returns errors as application/problem+json. With no token, or a wrong one, every v2 endpoint we called on 2026-11-15 returned exactly this, on both api.x.com and api.twitter.com:

{
"title": "Unauthorized",
"type": "about:blank",
"status": 401,
"detail": "Unauthorized"
}

Minting a bearer token with a wrong key or secret returns HTTP 403 with an older body:

{"errors":[{"code":99,"message":"Unable to verify your credentials","label":"authenticity_token_error"}]}
Status and type Cause Fix
401 about:blank, “Unauthorized” Missing, mistyped or regenerated token; wrong auth type Check the Authorization: Bearer header; copy a fresh token
403 code 99 on /oauth2/token Wrong API key or secret, or minting tokens too often Recheck the key and secret; cache the one bearer token
403 client-not-enrolled (.../client-forbidden) App not in the right package or environment Move the app to Pay-per-use and Production in the console
403 on a write or user endpoint Bearer token used where user context is needed, or missing scope Use OAuth 2.0 PKCE or OAuth 1.0a with the right scopes
403 on a reply The author did not summon your account Reply only where you were mentioned or quoted
429 .../rate-limit-exceeded Over the endpoint’s window Wait until x-rate-limit-reset, then back off
429 .../usage-capped Over a usage cap, such as 3 million post reads a cycle Wait for the next cycle or talk to X about Enterprise
Requests fail after a burst Credits ran out, or the spending limit was hit Add credits; raise the auto-recharge amount
400 .../invalid-request Bad or missing parameter, such as no query Read detail, which names the parameter
200 with an errors array Some requested IDs are deleted, private or missing Use the data you got; check resource_id in errors

The status codes and problem types come from X’s error reference. The 401 and code 99 bodies are the ones we recorded; the others were not observable without a funded app.

X MCP server setup for Claude, Cursor and ChatGPT

X runs an official hosted MCP server at https://api.x.com/mcp (streamable HTTP, server name xmcp), described on X’s MCP page. It lets an assistant search the full archive, look up users, read timelines and mentions, manage bookmarks, fetch trends and news, and draft and publish Articles, all billed to your own app’s credits. There are two ways in:

  • App-only bearer token. Point the client at the URL with an Authorization header. Read endpoints only, no acting as you, no token refresh.
  • The xurl bridge (xdevplatform/xurl, X’s official CLI). It runs locally through npx, does the OAuth 2.0 PKCE login in your browser once, caches the token in ~/.xurl and refreshes it. Your app needs OAuth 2.0 turned on and the redirect URI http://localhost:8080/callback registered.

Add ?read_only=true to the URL to hide and refuse every tool that posts, sends or changes anything, even if the token has write scopes. Use it for research agents.

Claude Code, read-only with a bearer token:

Terminal window
claude mcp add --transport http xapi "https://api.x.com/mcp?read_only=true" \
--header "Authorization: Bearer YOUR_APP_ONLY_BEARER_TOKEN"

Claude Code, acting as your account through the bridge:

Terminal window
claude mcp add xapi -e CLIENT_ID=YOUR_X_APP_CLIENT_ID -e CLIENT_SECRET=YOUR_X_APP_CLIENT_SECRET \
-- npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

Claude Desktop (claude_desktop_config.json, in %APPDATA%\Claude\ on Windows or ~/Library/Application Support/Claude/ on macOS) and Cursor (~/.cursor/mcp.json or .cursor/mcp.json) take the same bridge entry:

{
"mcpServers": {
"xapi": {
"command": "npx",
"args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
"env": {
"CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
"CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
}
}
}
}

Cursor also accepts the remote form with "url": "https://api.x.com/mcp" and a headers object holding the bearer token. The first launch opens a browser login; X recommends a startup timeout of at least 300 seconds so it can finish. If the login page says “You weren’t able to give access to the App”, the client ID and secret are not reaching xurl.

ChatGPT. X’s docs give no ChatGPT setup. ChatGPT adds remote servers under Plugins, Add custom MCP server, and accepts OAuth with static client credentials (OpenAI’s guide). X’s server publishes OAuth metadata at https://api.x.com/.well-known/oauth-protected-resource with PKCE but no dynamic client registration, so ChatGPT would need your own app’s client ID and secret and its callback URL registered on that app.

Docs server. For help writing X API code rather than calling the API, add {"x-docs": {"url": "https://docs.x.com/mcp"}}. Its tools are search_x and get_page_x.

Community servers on GitHub. All of them use your own X API credentials, so the prices above still apply:

  • xdevplatform/xmcp: X’s earlier self-hosted server, Python and FastMCP, exposing the OpenAPI spec as tools with an allowlist.
  • EnesCinr/twitter-mcp: three tools (post, search, home timeline) with OAuth 1.0a keys, run with npx -y @enescinar/twitter-mcp.
  • DataWhisker/x-mcp-server: 26 tools in TypeScript; its README’s pricing table predates the April 2026 changes.

A search of the official MCP registry on 2026-11-15 for “twitter” returned no entry published by X; most listings there front third-party data services rather than the X API.

Twitter scrapers: X’s terms and the court rulings

Scraping X without permission breaks X’s terms, and the case law so far limits what X can win in court without settling whether scraping is safe. This is a summary of documents, not legal advice.

X’s terms. The Terms of Service effective October 9, 2026 allow access only through X’s published interfaces and state that crawling or scraping without prior written consent is “expressly prohibited”. They set liquidated damages of $15,000 per 1,000,000 posts requested, viewed or accessed in any 24-hour period, and send disputes to state or federal courts in Wichita County or Tarrant County, Texas (outside the EU, EFTA and UK). X’s developer guidelines list scraping and browser automation as grounds for permanent suspension of a developer account.

X Corp. v. Bright Data Ltd., No. 3:23-cv-03698-WHA (N.D. Cal.). X sued a data-scraping company in 2023. Judge William Alsup’s orders, published on govinfo.gov:

  • May 9, 2024: complaint dismissed. The order held that X’s state-law claims “based on scraping and selling of data are preempted by the Copyright Act”, and that the claims about access to X’s systems were not adequately pleaded. X could seek leave to amend.
  • November 26, 2024: X allowed to proceed on amended access-based claims (trespass to chattels, unlawful and fraudulent business acts, tortious interference and breach of contract), with the court finding the new complaint “sufficiently alleges server impairment” from scrapers. The scraping-based claims for misappropriation, unjust enrichment, interference and contract breach were denied without leave to amend.
  • April 18, 2025: the scraping company’s antitrust counterclaims against X’s terms survived X’s motion to dismiss, except one California unfair-competition claim.

hiQ Labs v. LinkedIn (9th Cir. 2022). The Ninth Circuit held that accessing data a site makes public to everyone is likely not access “without authorization” under the federal Computer Fraud and Abuse Act. That answers the criminal-statute question only; contract and trespass claims are separate.

In practice: a scraper that logs in has accepted X’s terms through that account, the tools break whenever X changes its internal endpoints, and the accounts they use get suspended. For a supported way to read posts, the API’s per-item prices above are the cost of staying inside the rules.

Choosing a route for X data

  • Reading a few thousand posts a month for monitoring or research: pay-per-use with recent search and a bearer token.
  • Your own account’s data (posts, mentions, followers, bookmarks): Owned Reads at $0.001 per item.
  • Anything older than 7 days: full-archive search, open to pay-per-use accounts.
  • An AI agent that reads X: the hosted X MCP with ?read_only=true.
  • More than 3 million post reads a month, or the full stream: X’s Enterprise plans, priced by X on request.
  • Cited answers about what people said on X: Hyperresearch reads posts on X through the official API, the last seven days, as one of its 120+ data sources: in research runs, and in Answers in standard and max (standard adds a small per-search charge).

For other APIs an agent can call, see how to add web search to an AI agent, Claude Code as a research harness and deep research APIs with citations, compared.

Sources