@twexapi-dev/x-api-scraper

v0.1.3

Published

4 days ago

Twitter API alternative TypeScript SDK for tweet search, follower scraping, timelines, DMs, communities, lists, trending, and X automation. Agent Skills included. Not affiliated with X Corp.

Downloads

547

0High
0Medium
0Low

twexapi

twitter-api twitter-api-alternative x-api twitter-scraper tweet-search twitter-followers twitter-dm twitter-community trending typescript sdk twexapi mcp pi-package

TwexAPI TypeScript SDK: Twitter API for search, followers, DMs, communities & X automation

Use the TwexAPI TypeScript SDK to search tweets, scrape Twitter followers, and read X profiles, timelines, replies, and threads. Send DMs, search communities, fetch lists, articles, hashtags, cashtags, and global trending tweets with generated types and agent Skills. Like, retweet, follow, and post through documented REST routes. It is a Twitter API alternative for apps, scripts, and MCP clients.

API Map | REST API | MCP Guide | Dashboard

Speakeasy generates this SDK.

Pi coding agent package

Install the bundled TwexAPI Skills directly from npm:

pi install npm:@twexapi-dev/x-api-scraper

Pi loads the packaged Skills from skills/:

x-api-scraper — routing, safety, SDK, and reference files
x-api-scraper-research — bounded public research reads

Import the typed SDK from the same npm package.

Common Twitter & X tasks

| Task | REST Route | Usage | | ------------------------------- | -------------------------------------------------- | ----------------------------------------------- | | Search tweets without the X API | POST /twitter/advanced_search/page | Use keyword queries and paginate with a cursor. | | Search hashtags or cashtags | POST /twitter/hashtags, POST /twitter/cashtags | Filter by tag and sort order. | | Read an X profile | GET /twitter/{screen_name}/about | Look up a user by screen name. | | Read a profile timeline | GET /twitter/{screen_name}/timeline/page | Paginate bounded results. | | Scrape Twitter followers | POST /v3/twitter/users/followers | Use the v3 follower list. | | Scrape following accounts | POST /v3/twitter/users/following | Use the v3 following list. | | Read tweet replies | POST /twitter/tweets/{tweet_id}/replies/page | Paginate replies by tweet id. | | Read a tweet thread | POST /twitter/tweets/thread_by_id | Fetch the thread from a root tweet. | | Send or read DMs | /v3/twitter/send-dm, /v3/twitter/dm-history | Use v3 XChat endpoints. | | Search communities | POST /twitter/community/search | Find communities, then load tweets or members. | | Get global trending tweets | GET /twitter/global-trending/tweets | Filter by country, topic, and content. | | Post or reply | POST /twitter/tweets/create | Confirm the account cookie and payload. |

See api.md for the complete API.

AI agent workflows with MCP

Use the typed REST SDK in application code. Add https://api.twexapi.io/mcp to MCP clients. Follow the MCP guide for current authentication support.

Package & registry trust

Package: npm @twexapi-dev/x-api-scraper
Source: twexapi-dev/x-api-scraper-typescript
Docs: docs.twexapi.io
License: MIT
Dashboard: twexapi.io/dashboard

Installation

Requires a JavaScript runtime with ECMAScript 2020 and fetch. See RUNTIMES.md.

npm install @twexapi-dev/x-api-scraper

pnpm, bun, and yarn also work.

Usage

See api.md for the complete API.

Get an API key from the TwexAPI dashboard. Pass it as bearerAuth, or set X_API_SCRAPER_KEY.

import { XApiScraper } from "@twexapi-dev/x-api-scraper";

const client = new XApiScraper({
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

const result = await client.search.advanced({
  searchTerms: ["from:elonmusk"],
  sortBy: "Latest",
  nextCursor: "",
});

Look up a profile and paginate followers:

const about = await client.users.getAbout({ screenName: "elonmusk" });

const followers = await client.users.followers.list({
  screenName: "elonmusk",
});

Keep API keys out of source code, URLs, and logs.

Authentication

This SDK uses HTTP Bearer authentication. Set bearerAuth when creating the client.

Write actions (tweet, follow, like, DM send) also need a Twitter cookie or auth_token on the request. Pass them on the operation input.

Request & response types

The package includes types for every request parameter and response field. Import them directly:

import { XApiScraper } from "@twexapi-dev/x-api-scraper";
import type {
  AdvancedSearchCursorQuery,
  AdvancedSearchCursorResponse,
} from "@twexapi-dev/x-api-scraper/models";

const client = new XApiScraper({
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

const params: AdvancedSearchCursorQuery = {
  searchTerms: ["from:elonmusk"],
  sortBy: "Latest",
  nextCursor: "",
};
const result: AdvancedSearchCursorResponse = await client.search.advanced(params);

Editors show each method, parameter, and field description from its docstring.

Available Resources and Operations

Available methods

Account

balance - Get Balance

Analysis

sentiment - Sentiment Analysis

Articles

fetch - Batch Fetch X Articles
markdown - Fetch Article as Markdown

Communities

members - Get Community Members
membersPage - Get Community Members by Page
tweets - Get Community Tweets
tweetsPage - Get Community Tweets by Page
search - Search Community
get - Get Community
searchTweets - Search Community Tweets

Dm

status - Check DM Permissions
send - Send DM
history - Get DM History
media - Get DM Media
conversations - Get Conversations

Lists

tweets - Get List Tweets
tweetsPage - Get List Tweets by Page
subscribers - Get List Subscribers
members - Get List Members
membersPage - Get List Members by Page
search - Search List

Search

advanced - Advanced Twitter Search by Page
cashtags - Search Cashtags
hashtags - Search Hashtags

Timelines

tweetsAndReplies - Get All Tweets and Replies by User
userPage - Get User Timeline by Page
user - Get User Timeline and Fill Count
tweetsAndRepliesPage - Get All Tweets and Replies by User by Page

Tweets

detail - Get Tweet Detail
thread - Get Tweet Thread by ID
lookup - Batch Get Tweets by ID
similar - Get Similar Tweets

Tweets.Actions

like - Like a Tweet
unlike - Unlike a Tweet
retweet - Retweet a Tweet
unretweet - Delete Retweet
createThread - Create a Tweet Thread
create - Create a Tweet or Reply
quote - Create a Quote Tweet
createWithoutCookie - Post Tweet (Auto Cookie)
bookmark - Bookmark a Tweet
unbookmark - Delete Bookmark
deleteBatch - Delete One or More Tweets

Tweets.Engagement

retweeters - Get Retweeters
retweetersPage - Get Retweeters by Page
quotes - Get Quote Tweets
quotesPage - Get Quote Tweets by Page

Tweets.Replies

page - Get Replies by Page

Users

getByUsernames - Get Multiple Users by Usernames
getByIds - Users Details by ID
verifyAccount - Verify Account Status
getStatuses - Batch Get User account status
search - Search User
follow - Follow User
unfollow - Unfollow User
getAccountBased - Get Twitter Account Based in
getAbout - Get Twitter User About by Screen Name

Users.Followers

list - Get Followers (v3)
verified - Get Verified Followers

Users.Following

list - Get Following (v3)

Standalone functions

All of the methods above are also exported as standalone functions for tree-shaking. See FUNCTIONS.md.

Handling errors

XAPIScraperError is the base class for HTTP error responses.

import { XApiScraper } from "@twexapi-dev/x-api-scraper";
import * as errors from "@twexapi-dev/x-api-scraper/models/errors";

const client = new XApiScraper({
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

try {
  await client.search.advanced({
    searchTerms: ["from:elonmusk"],
    sortBy: "Latest",
    nextCursor: "",
  });
} catch (error) {
  if (error instanceof errors.XAPIScraperError) {
    console.log(error.statusCode);
    console.log(error.body);
  } else {
    throw error;
  }
}

| Property | Type | Description | | ------------------- | ---------- | ------------------ | | error.message | string | Error message | | error.statusCode | number | HTTP status code | | error.headers | Headers | Response headers | | error.body | string | Response body | | error.rawResponse | Response | Raw fetch response |

Network errors include ConnectionError, RequestTimeoutError, and RequestAbortedError. Validation failures may throw HTTPValidationError (422).

Retries

Some operations support retries. The SDK uses exponential backoff by default.

Override retries per request:

import { XApiScraper } from "@twexapi-dev/x-api-scraper";

const client = new XApiScraper({
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

const result = await client.search.advanced(
  {
    searchTerms: ["from:elonmusk"],
    sortBy: "Latest",
    nextCursor: "",
  },
  {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  },
);

Or set retryConfig on the client for every operation that supports retries.

Timeouts

Set timeoutMs on the client or on one request. Timed-out requests throw RequestTimeoutError.

const client = new XApiScraper({
  timeoutMs: 20 * 1000,
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

await client.search.advanced(
  {
    searchTerms: ["from:elonmusk"],
    sortBy: "Latest",
    nextCursor: "",
  },
  {
    timeoutMs: 5 * 1000,
  },
);

Server selection

The default server is https://api.twexapi.io. Override it with server: "production" or serverURL.

const client = new XApiScraper({
  serverURL: "https://api.twexapi.io",
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

Logging

[!WARNING] Debug logs can include API tokens. Use this only during local development.

Pass debugLogger: console to log requests and responses.

const client = new XApiScraper({
  debugLogger: console,
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

Custom HTTP client

The SDK uses the global fetch function by default.

Polyfill the global to use another fetch implementation:

import fetch from "my-fetch";

globalThis.fetch = fetch;

Or pass an HTTPClient with a custom fetcher:

import { XApiScraper } from "@twexapi-dev/x-api-scraper";
import { HTTPClient } from "@twexapi-dev/x-api-scraper/lib/http";
import fetch from "my-fetch";

const httpClient = new HTTPClient({ fetcher: fetch });
const client = new XApiScraper({
  httpClient,
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

Fetch options

Pass RequestInit fields on a request without replacing fetch. Request options take precedence.

await client.search.advanced(
  {
    searchTerms: ["from:elonmusk"],
    sortBy: "Latest",
    nextCursor: "",
  },
  {
    headers: {
      "X-Custom-Header": "value",
    },
  },
);

Proxies

Add runtime-specific proxy settings through a custom HTTPClient fetcher.

Node [docs]

import { XApiScraper } from "@twexapi-dev/x-api-scraper";
import { HTTPClient } from "@twexapi-dev/x-api-scraper/lib/http";
import * as undici from "undici";

const proxyAgent = new undici.ProxyAgent("http://localhost:8888");
const httpClient = new HTTPClient({
  fetcher: (input, init) =>
    fetch(input, { ...init, dispatcher: proxyAgent } as RequestInit),
});

const client = new XApiScraper({
  httpClient,
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

Bun [docs]

import { XApiScraper } from "@twexapi-dev/x-api-scraper";
import { HTTPClient } from "@twexapi-dev/x-api-scraper/lib/http";

const httpClient = new HTTPClient({
  fetcher: (input, init) =>
    fetch(input, { ...init, proxy: "http://localhost:8888" } as RequestInit),
});

const client = new XApiScraper({
  httpClient,
  bearerAuth: process.env.X_API_SCRAPER_KEY,
});

Deno [docs]

import { XApiScraper } from "npm:@twexapi-dev/x-api-scraper";
import { HTTPClient } from "npm:@twexapi-dev/x-api-scraper/lib/http";

const denoHttp = Deno.createHttpClient({
  proxy: { url: "http://localhost:8888" },
});
const httpClient = new HTTPClient({
  fetcher: (input, init) =>
    fetch(input, { ...init, client: denoHttp } as RequestInit),
});

const client = new XApiScraper({
  httpClient,
  bearerAuth: Deno.env.get("X_API_SCRAPER_KEY"),
});

Semantic versioning

This package follows SemVer with these exceptions:

Static type changes that preserve runtime behavior.
Changes to undocumented internals that remain technically public.
Changes unlikely to affect normal use.

Open an issue with questions, bugs, or suggestions.

Runtime support

Supports these runtimes:

Current Chrome, Firefox, Safari, Edge, and other web browsers.
Maintained Node.js 18 LTS or later.
Deno v1.39 or higher.
Bun 1.0 or later.
Cloudflare Workers.
Vercel Edge Runtime.

See RUNTIMES.md for compiler options and runtime notes.

React Native is not supported.

Request another runtime in a GitHub issue.

Contributing

This repository contains generated code. See CONTRIBUTING.md.

To regenerate the Speakeasy input spec:

node --test tests/build-openapi-sdk.test.mjs
node scripts/build-openapi-sdk.mjs openapi.source.json openapi.sdk.json docs/openapi-prep-report.json docs/openapi-prep-report.md

TwexAPI is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.