Migrate read calls from the official X API to TwittrAPI

This guide moves data reads from X API v2 to TwittrAPI. It does not cover posting on behalf of users or user-context OAuth, which belong on the official API. X API paths and parameters come from docs.x.com as of October 2026. Ours are checked against our endpoint reference; every TwittrAPI path below links to its reference page. For prices and trade-offs, read the comparison first.

What changes

Endpoint mapping

Response shape

A v2 post is data with public_metrics, and the author sits in includes.users, joined by author_id. In TwittrAPI's response the author is inside the post, and the counts use X's older names:

Timelines wrap posts in instructions and entries. The response format docs show the structure, and our examples repository has extractors for Python, Node.js and Go.

Before and after: Python

Before, with the X API:

import os, requests
 
r = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers={"Authorization": f"Bearer {os.environ['X_BEARER_TOKEN']}"},
    params={
        "query": "from:jack -is:retweet",
        "max_results": 100,
        "post.fields": "created_at,public_metrics",  # older docs and clients call it tweet.fields
        "expansions": "author_id",
    },
)
body = r.json()
users = {u["id"]: u["username"] for u in body.get("includes", {}).get("users", [])}
for p in body.get("data", []):
    print(p["id"], users.get(p["author_id"]), p["public_metrics"]["like_count"], p["text"])
next_token = body.get("meta", {}).get("next_token")

After, with the Python SDK and the extractor from the examples repository:

from twittrapi import TwittrAPI
from extract import tweets  # python/_shared/extract.py from the examples repo
 
client = TwittrAPI()  # reads TWITTRAPI_API_KEY
 
for page in client.paginate(client.search.tweets, "from:jack -filter:retweets", category="Latest", max_pages=5):
    for t in tweets(page):
        print(t["id"], t["author"], t["likes"], t["text"])

Note the operator change: v2's -is:retweet is -filter:retweets (or -filter:nativeretweets) in X's search box syntax.

Before and after: Node.js

Before:

const res = await fetch("https://api.x.com/2/users/by/username/jack", {
  headers: { Authorization: `Bearer ${process.env.X_BEARER_TOKEN}` },
});
const { data } = await res.json();
const followers = await fetch(`https://api.x.com/2/users/${data.id}/followers?max_results=1000`, {
  headers: { Authorization: `Bearer ${process.env.X_BEARER_TOKEN}` },
}).then((r) => r.json());

After, with the Node SDK:

import { TwittrAPI } from "twittrapi";
import { extractProfile, extractUsers } from "./extract.mjs"; // node/_shared/extract.mjs from the examples repo
 
const client = new TwittrAPI(); // reads TWITTRAPI_API_KEY
 
const profile = extractProfile(await client.users.getByUsername("jack"));
for await (const page of client.paginate(client.users.followers, { userId: profile.id, count: 100 }, { maxPages: 5 })) {
  for (const u of extractUsers(page.data)) console.log(u.username, u.followers);
}

Pagination differences

• pagination_token becomes cursor, and meta.next_token becomes the bottom cursor in the response. The SDKs find it for you; see Pagination.
• There is no result_count. Count the items you extract.
• v2 lets you ask for up to 1,000 followers per request^{as of Oct 2026}. Our page size follows X's web app; set count and check what comes back, since every page is a billed call.
• since_id / until_id and start_time / end_time become search operators: since_id:, max_id:, since:, until:, since_time:, until_time:.

Billing and limits

• One request is one call, whatever it returns. There is no 24-hour deduplication, so cache what you re-read often.
• The rate limit is per second for all endpoints together (30 requests per second after the first top-up). 429 is not charged. See Rate limits.
• Calls that end in 400, 408, 409 or 5xx are refunded (X-Refunded: true).
• There is no monthly read cap.

Checklist

• Split your X API usage into reads and everything else (posting for users, OAuth, DMs). Move only the reads.
• Map each read endpoint with the table above; plan around Spaces, counts and streaming if you use them.
• Create an account at /start and set TWITTRAPI_API_KEY.
• Replace post.fields / expansions handling with an extractor for X's GraphQL JSON.
• Convert v2-only search operators (is:retweet, has:media) to X search box operators (filter:retweets, filter:media).
• Replace pagination_token loops with cursor pagination or the SDK paginator.
• Parse legacy.created_at if you store ISO dates.
• Run both on a sample of your queries and compare results and cost.
• Switch the reads; keep the official API for the rest.

TwittrAPI is a third-party service and is not affiliated with X Corp. Reading data needs no X account; optional account actions use your own X session cookie and proxy. Make sure an unofficial API fits your compliance requirements before you move production traffic.

Frequently asked questions

Should I move everything off the official X API?

No. Keep the official API for posting on behalf of users, OAuth flows, full-archive search and anything that needs an agreement with X. Move the reads where the price per post is the problem.

What replaces post.fields and expansions?

Nothing. TwittrAPI returns everything X's web app receives for the request, including the author inside each tweet. You pick the fields when you parse.

How do I get replies to a post?

On the X API you search for conversation_id: followed by the post ID. On TwittrAPI, GET /tweet/{tweetId} returns the post and its replies, about 20 per page, with a cursor for more. Search with conversation_id: also works.

Are user and post IDs the same?

Yes. Both use X's numeric IDs, so stored IDs keep working.