@kaitoinfra/twitterapi

Official TypeScript SDK + CLI for twitterapi.io — Twitter/X data API. Search tweets, fetch user profiles, followers, replies, retweeters, trends. One API key, no OAuth, no Twitter Developer Account.

Install

npm install @kaitoinfra/twitterapi
# or
pnpm add @kaitoinfra/twitterapi
# or
yarn add @kaitoinfra/twitterapi

Get an API key

Sign up at twitterapi.io — free tier available.

Quick start (SDK)

import { TwitterApiClient } from "@kaitoinfra/twitterapi";

const client = new TwitterApiClient({ apiKey: process.env.TWITTERAPI_TOKEN! });

// User profile
const user = await client.getUserInfo({ userName: "elonmusk" });
console.log(user);

// Advanced search
const tweets = await client.searchTweets({
  query: "from:elonmusk has:images since:2026-01-01",
  queryType: "Latest",
});

// Pagination
let cursor: string | undefined;
do {
  const page = await client.getUserFollowers({ userName: "elonmusk", cursor });
  // ...process page...
  cursor = (page as any).next_cursor;
} while (cursor);

CLI

export TWITTERAPI_TOKEN=your_api_key

npx twitterapi user-info elonmusk
npx twitterapi search "from:elonmusk has:images" Latest
npx twitterapi trends 1 10  # 1 = Worldwide

npx twitterapi help

All output is JSON to stdout — pipe to jq for filtering:

npx twitterapi user-info elonmusk | jq '.data.followers'

API reference

12 read endpoints (v0.1.0):

| Method | Endpoint | |---|---| | searchTweets(params) | Advanced search (Twitter operators) | | getUserInfo(params) | Basic user profile | | getUserAbout(params) | Extended "about" page | | getUserFollowers(params) | Paginated followers | | getUserFollowings(params) | Paginated followings | | getUserLastTweets(params) | Recent tweets | | getUserMentions(params) | Tweets mentioning user | | getTweetsByIds(params) | Batch fetch (≤100) | | getTweetReplies(params) | Replies to a tweet | | getTweetQuotes(params) | Quote-tweets | | getTweetRetweeters(params) | Retweeters | | getTrends(params) | Trending topics by WOEID |

Need a write or stream endpoint not exposed here? Use the low-level escape hatch.

Low-level escape hatch

For any twitterapi.io endpoint not wrapped above:

const result = await client.get("/twitter/some/new/endpoint", { foo: "bar" });

The full REST API is documented at twitterapi.io/docs.

Error handling

Failed requests throw TwitterApiError:

import { TwitterApiClient, TwitterApiError } from "@kaitoinfra/twitterapi";

try {
  await client.getUserInfo({ userName: "nonexistent_user_xyz" });
} catch (e) {
  if (e instanceof TwitterApiError) {
    console.error(`API ${e.status}: ${e.message}`);
  }
}

Automatic retry on 429 / 5xx (up to 3 attempts, exponential backoff).

MCP server (alternative)

If you're building an AI agent (Claude.ai, Claude Code, Cursor), use the hosted MCP server instead:

URL: https://mcp.twitterapi.io/mcp
Install: claude mcp add --transport http --scope user twitterapi-mcp \
  https://mcp.twitterapi.io/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Or the stdio version: @kaitoinfra/twitterapi-io-mcp-server

License

MIT