Fetch a user's X/Twitter timeline — their tweets, replies, likes, media posts, or mentions — plus follower and following lists, and per-tweet engagement lists (who replied, quoted, retweeted, or favorited). Billed per item returned. The building block for monitoring what an account posts or ranking accounts by activity. No signup, no API keys — every request is paid in USDC through the HTTP 402 flow, and the exact price is quoted before you pay.
One endpoint: POST /api/tools/x_timeline over HTTP, or the x_timeline tool over MCP at POST /api/mcp.
curl -X POST https://twitr.sh/api/tools/x_timeline \
-H 'Content-Type: application/json' \
-d '{"kind":"user-tweets","id":"elonmusk","resultsLimit":100}'
# → 402 Payment Required with the exact USDC price.
# Pay it (x402 on Base/Solana, MPP on Tempo) and retry the same request → 200 + data.
# x402-aware clients do both steps automatically.kind selects the timeline: user-tweets|user-replies|user-likes|user-media|user-mentions|followers|following|verified-followers (id = user) or tweet-replies|tweet-quotes|tweet-thread|tweet-favoriters|tweet-retweeters (id = tweet). resultsLimit is MANDATORY — billed per item returned. Search-operator filters (fromUser, language, mediaType, minFaves, …) apply to tweet timelines.
The exact quote is returned in the 402 challenge before you pay — an agent always knows the cost first. Failed calls are never charged. Full input schema in the OpenAPI spec.
Fetch a user's X/Twitter timeline — their tweets, replies, likes, media posts, or mentions — plus follower and following lists, and per-tweet engagement lists (who replied, quoted, retweeted, or favorited). Billed per item returned. The building block for monitoring what an account posts or ranking accounts by activity. It is one of 14 pay-per-call X/Twitter tools on twitr.sh, available over HTTP (POST /api/tools/x_timeline) and MCP (tool name x_timeline).
$0.0012–$1.20 per call in USDC. The exact quote is returned in the 402 challenge before you pay — an agent always knows the cost first. Failed calls are never charged.
POST https://twitr.sh/api/tools/x_timeline with your input. The first response is HTTP 402 Payment Required carrying the exact price; pay it in USDC (x402 on Base or Solana, MPP on Tempo) and retry the identical request to get the data. No signup — the wallet is the account.
Yes. Call the x_timeline tool via the MCP endpoint at POST https://twitr.sh/api/mcp — tools/list is free, tools/call is payment-gated with a JSON-RPC 402. The installable agent skill at https://twitr.sh/skill.md covers the full workflow.