Migrate from twitterapi.io to TwittrAPI

This guide moves a twitterapi.io read integration to TwittrAPI. twitterapi.io paths and parameters are taken from its public docs as of October 2026. Ours are checked against our endpoint reference; every TwittrAPI path below links to its reference page. Before you start, read the comparison to make sure the switch makes sense for your workload.

What changes

Endpoint mapping

Rows that show a twitterapi.io page title instead of a path are endpoints whose exact path we did not copy from its docs; look them up there.

Before and after: Python

Before, with requests against twitterapi.io:

import os, requests
 
r = requests.get(
    "https://api.twitterapi.io/twitter/tweet/advanced_search",
    headers={"X-API-Key": os.environ["TWITTERAPI_IO_KEY"]},
    params={"query": "from:jack lang:en", "queryType": "Latest", "cursor": ""},
)
data = r.json()
for t in data["tweets"]:
    print(t["id"], t["author"]["userName"], t["likeCount"], t["text"])
next_cursor = data["next_cursor"] if data["has_next_page"] else None

After, with the Python SDK (pip install twittrapi). tweets() is the extractor from our examples repository; it flattens X's JSON into simple dicts:

from twittrapi import TwittrAPI, extract_bottom_cursor
from extract import tweets  # python/_shared/extract.py from the examples repo
 
client = TwittrAPI()  # reads TWITTRAPI_API_KEY
 
page = client.search.tweets("from:jack lang:en", category="Latest", count=20)
for t in tweets(page):
    print(t["id"], t["author"], t["likes"], t["text"])
next_cursor = extract_bottom_cursor(page)  # None at the end

To walk several pages, let the SDK follow the cursor. Every page is one billed call:

for page in client.paginate(client.search.tweets, "from:jack lang:en", category="Latest", max_pages=5):
    for t in tweets(page):
        ...

Before and after: Node.js

Before:

const res = await fetch(
  "https://api.twitterapi.io/twitter/user/last_tweets?userName=jack&cursor=",
  { headers: { "X-API-Key": process.env.TWITTERAPI_IO_KEY } },
);
const data = await res.json();
for (const t of data.tweets) console.log(t.id, t.likeCount, t.text);

After, with the Node SDK (npm install twittrapi):

import { TwittrAPI, extractBottomCursor } from "twittrapi";
import { extractTweets } from "./extract.mjs"; // node/_shared/extract.mjs from the examples repo
 
const client = new TwittrAPI(); // reads TWITTRAPI_API_KEY
 
const page = await client.users.tweets({ username: "jack", count: 20 });
for (const t of extractTweets(page)) console.log(t.id, t.likes, t.text);
const cursor = extractBottomCursor(page); // undefined at the end

Keep your data model: an adapter

If the rest of your code expects twitterapi.io's tweet objects, map ours to that shape in one place:

def to_twitterapi_io_shape(t: dict) -> dict:
    """t is one item from tweets(page)."""
    return {
        "id": t["id"],
        "url": t["url"],
        "text": t["text"],
        "createdAt": t["created_at"],
        "likeCount": t["likes"],
        "retweetCount": t["retweets"],
        "replyCount": t["replies"],
        "viewCount": t["views"],
        "author": {"userName": t["author"]},
    }

Fields twitterapi.io adds that the extractor does not (for example bookmarkCount or quoteCount) are in X's JSON under the tweet's legacy object; extend the extractor if you use them. The response format docs explain where things are.

Pagination differences

• Leave cursor out on the first page instead of sending an empty string.
• There is no has_next_page. Stop when there is no bottom cursor, when it repeats, or when a page has no items. See Pagination.
• Page sizes differ. A twitterapi.io follower page can hold up to 200 accounts; on our side set count and check what comes back.
• Cursors are not interchangeable. Start fresh on our side; do not reuse stored twitterapi.io cursors.

Errors and billing

Errors are {"error": "..."} with an HTTP status. 401 means a missing or unknown key, 402 no balance, 429 over your per-second limit (not charged). Calls that end in 400, 408, 409 or 5xx are refunded, and the X-Refunded header says so. Every billed response has X-Price-Per-Call and X-Remaining-Balance headers, which helps when you compare costs during the switch. Details: Errors and Pricing and billing.

Checklist

• List every twitterapi.io endpoint you call and how often.
• Check each against the mapping table; plan around Spaces, follower ID lists and webhooks if you use them.
• Create an account at /start and set TWITTRAPI_API_KEY.
• Install the SDK (pip install twittrapi or npm install twittrapi) or switch the base URL and header.
• Replace userName lookups on timelines with user IDs, or use -1 plus ?username=.
• Write the adapter from X's JSON to your data model, and test it on saved responses.
• Replace has_next_page checks with bottom-cursor checks; do not reuse old cursors.
• Map error handling to our status codes; back off on 429.
• Run both services side by side on a sample, compare items and cost.
• Move the rest of the traffic.

Reading data needs no X account; the optional account actions use your own X session cookie and proxy. TwittrAPI is not affiliated with X Corp. or twitterapi.io.

Frequently asked questions

How long does a migration from twitterapi.io take?

The HTTP calls change quickly. Most of the work is the response parser, because twitterapi.io returns flat camelCase objects and TwittrAPI passes X's own JSON through. With an adapter that maps our JSON to the objects your code already uses, the rest of your code does not change.

Do I need a username or a user ID?

Our user timelines take a numeric user ID in the path. If you only have a handle, pass -1 as the ID and add ?username=. It is still one call, just a little slower.

Is there an equivalent of has_next_page?

No. Look for the bottom cursor in the response. If there is none, or it repeats, or the page holds no items, you are at the end. The SDK paginator does those checks for you.

Can I run both services during the switch?

Yes. Put both behind the same adapter interface and route a share of traffic to each until the results match.