x-twitter-data

X data — reads, search, timelines

Task	Tool
One tweet, profile, article, follow-check, trends	POST /api/tools/x_read
Search tweets or users	POST /api/tools/x_search
Timelines, follower graphs, engagement lists	POST /api/tools/x_timeline
List timelines, members, followers	POST /api/tools/x_lists
Community info, members, posts, in-community search	POST /api/tools/x_communities
Trending topics by region/category	POST /api/tools/radar (tool name x_radar; category: general|tech|dev|science|culture|politics|business|entertainment)

Base URL https://twitr.sh. Every call is one POST. Prices are per returned item on the volume tools, ~$0.0012 per unit, floor $0.001.

Calling it

The first request returns 402 with the exact price; an x402 client pays and retries automatically. With AgentCash MCP:

mcp__agentcash__fetch({
  url: "https://twitr.sh/api/tools/x_search",
  method: "POST",
  body: { kind: "tweets", q: "from:vercel launch", resultsLimit: 50 }
})

Read amount and breakdown from the 402 before signing. Tell the user the cost for anything non-trivial, and confirm above ~$0.10.

Gotchas

• resultsLimit is mandatory on volume tools (search, timelines, lists, some reads) — the call is rejected before charging without it. It's also the spend rail: you pay per returned item, so resultsLimit: 1000 is a ~$1.20 call.
• Failed calls are never charged. A 4xx/5xx costs nothing, so retry freely on errors.
• User ids are numeric, not handles. Anything taking a user id wants the numeric form — get it from x_read {"resource":"get-user","username":"..."}.
• x_read batch mode takes up to 100 ids in one call, far cheaper than 100 single calls.
• x_radar is priced at the floor ($0.001), so trend checks are effectively free — use it before search when the question is "what's happening".

Avoid

• Don't paginate blindly to "get everything" — set resultsLimit to what's actually needed.
• Don't call a read repeatedly for the same id in one session; cache it in context.
• Don't use this for datasets over a few hundred rows — x-twitter-research runs those async and returns a downloadable file instead of flooding context.