A Twitter scraper API: tweets, profiles and followers from one call.

What can you scrape from Twitter/X?

Full input schemas are in /openapi.json, and each tool has its own page under /tools.

How does a scrape call work?

Every tool takes a flat JSON body. Your first request, with no credentials, returns HTTP 402 Payment Required with the exact amount, a line-item breakdown and what an empty result would cost ($0). Your wallet signs a USDC payment and retries the same request, and you get the data. Fixed-price calls accept x402 on Base or Solana and MPP on Tempo. Per-result reads settle on Base and charge only for records returned. Volume tools require a resultsLimit, so you never pay for more than you asked for.

How do I call it with curl?

# 1) unpaid probe: returns the price
curl -i -X POST https://twitr.sh/api/tools/x_search \
  -H 'Content-Type: application/json' \
  -d '{"q":"from:nasa","queryType":"Latest","resultsLimit":20}'
# -> HTTP/2 402
#    "amount": "0.024000", "billing": "per-returned-record"
#    "breakdown": [{ "label": "20 results × $0.001200" }]

# 2) pay from a USDC wallet and retry, capped at 5 cents
npx agentcash fetch https://twitr.sh/api/tools/x_search -m POST \
  -b '{"q":"from:nasa","queryType":"Latest","resultsLimit":20}' \
  --max-amount 0.05

New to the wallet? npx agentcash try https://twitr.sh lists every tool and walks you through the first call.

How do I call it from Python?

import requests

URL = "https://twitr.sh/api/tools/x_search"
body = {"q": "from:nasa", "queryType": "Latest", "resultsLimit": 20}

# 1) unpaid probe: the 402 body carries the exact price
quote = requests.post(URL, json=body)
print(quote.status_code, quote.json()["amount"])  # 402 0.024000

# 2) paid call from a card-funded balance
r = requests.post(URL, json=body, headers={"Authorization": "Bearer tw_live_..."})
for tweet in r.json()["items"]:
    print(tweet["id"], tweet["text"])

How do I call it from Node?

const url = "https://twitr.sh/api/tools/x_search";
const body = JSON.stringify({ q: "from:nasa", queryType: "Latest", resultsLimit: 20 });
const headers = { "Content-Type": "application/json" };

// 1) unpaid probe
const quote = await fetch(url, { method: "POST", headers, body });
console.log(quote.status, (await quote.json()).amount); // 402 "0.024000"

// 2) paid call from a card-funded balance
const res = await fetch(url, {
  method: "POST",
  headers: { ...headers, Authorization: `Bearer ${process.env.TWITR_API_KEY}` },
  body,
});
const { items } = await res.json();

To pay from a wallet inside your own code, wrap fetch or requests with an x402 client library, such as Coinbase's @x402/fetch or the x402 Python package. Per-result reads use the upto scheme on Base. API keys come from the dashboard after a Google sign-in, and the prices are the same either way.

How do I scrape more than 2,500 items?

Synchronous reads return up to 2,500 items per call. For bigger jobs, such as every follower of a large account or every reply to a viral post, use x_extract. It runs 23 extractors as async jobs of up to 10,000 rows. You pay up front for the resultsLimit you ask for and get a claim check straight away. Then you poll a free status URL until the dataset is ready to download:

# start the job (Idempotency-Key makes retries safe)
npx agentcash fetch https://twitr.sh/api/tools/x_extract -m POST \
  -H 'Idempotency-Key: nasa-followers-001' \
  -b '{"tool":"follower_explorer","targetUsername":"nasa","resultsLimit":10000}'
# -> {"snapshot_id":"sd_ex_...","status":"pending","status_url":"/api/snapshots/sd_ex_..."}

# poll for free with the same wallet until status is "ready"
npx agentcash fetch https://twitr.sh/api/snapshots/sd_ex_...

The extractors cover followers, following, verified followers, posts, replies, reposts, quotes, threads, articles, likers, mentions, user likes and media. They also cover community members, moderators and posts, list members, posts and followers, Spaces, people search and tweet search. Ten thousand rows cost $12.

How does it compare with building a scraper yourself?

The cheapest Apify Actors cost less per tweet for big batch jobs. See the Apify comparison and the official API comparison for the full trade-offs.

Is it legal to scrape Twitter?

There is no single answer. X's terms of service prohibit crawling or scraping without its prior written consent. Whether collecting public posts is lawful depends on your jurisdiction and purpose. Personal data in tweets is still personal data under privacy laws such as the GDPR. twitr.sh is not affiliated with X, and the only access X sanctions is its own API (see X API pricing and X API alternatives). Collect only what you need, and check X's terms and your local law first.

Can an AI agent use it directly?

Yes. That is what it was built for. Point Claude Code, Cursor or any MCP client at https://twitr.sh/api/mcp (listing tools is free), or install the skills with npx skills add lnvestor/twitr-skills. Then ask in plain English: “export everyone who replied to this tweet” or “what has @nasa posted this week?” The docs cover setup. To try the data free first, run the shadowban checker or the X algorithm checker.

FAQ