Fetch a user's X/Twitter timeline — their tweets, replies, likes, media posts, or mentions
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.
120000 (raw units)
price
9
calls / 30d
3
unique payers
2026-09-15
updated
Provider
twitr.sh · discovered, not yet claimed by its owner
Payment (x402 accepts[])
[
{
"scheme": "upto",
"network": "eip155:8453",
"payTo": "0xb5194A98DbDBb7028B585Db26B972e7F0F3f826A",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"amount": "120000",
"maxTimeoutSeconds": 300
}
]Output schema
{
"bazaar": {
"category": "api",
"discoverable": true,
"info": {
"input": {
"body": {
"id": "elonmusk",
"kind": "user-tweets",
"resultsLimit": 100
},
"bodyType": "json",
"method": "POST",
"type": "http"
},
"output": {
"example": {
"duration": 3,
"items": [
{
"authorUsername": "elonmusk",
"createdAt": "2026-02-24T10:05:00.000Z",
"id": "1893710452812718080",
"likeCount": 1180,
"text": "This is a great thread, thanks for sharing."
}
],
"payment": {
"amount": "0.120000",
"currency": "USD",
"protocol": "x402"
},
"runId": "tw_example"
},
"type": "json"
}
},
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"input": {
"additionalProperties": false,
"properties": {
"body": {
"properties": {
"id": {
"description": "User ID/username or tweet ID (depends on kind).",
"type": "string"
},
"includeParentTweet": {
"type": "boolean"
},
"includeReplies": {
"type": "boolean"
},
"kind": {
"description": "Which timeline to fetch.",
"enum": [
"user-tweets",
"user-replies",
"user-likes",
"user-media",
"user-mentions",
"followers",
"following",
"verified-followers",
"tweet-replies",
"tweet-quotes",
"tweet-thread",
"tweet-favoriters",
"tweet-retweeters"
],
"type": "string"
},
"language": {
"type": "string"
},
"mediaType": {
"enum": [
"images",
"videos",
"gifs",
"media"
],
"type": "string"
},
"minFaves": {
"type": "integer"
},
"resultsLimit": {
"description": "MANDATORY: max items returned, billed per item.",
"maximum": 10000,
"minimum": 1,
"type": "integer"
},
"verifiedOnly": {
"type": "boolean"
}
},
"required": [
"kind",
"id",
"resultsLimit"
],
"type": "object"
},
"bodyType": {
"enum": [
"json",
"form-data",
"text"
],
"type": "string"
},
"method": {
"enum": [
"POST",
"PUT",
"PATCH"
],
"type": "string"
},
"type": {
"const": "http",
"type": "string"
}
},
"required": [
"type",
"method",
"bodyType",
"body"
],
"type": "object"
},
"output": {
"properties": {
"example": {
"properties": {
"duration": {
"description": "Run duration in seconds.",
"type": "integer"
},
"items": {
"description": "Returned items. Shape varies per tool — see each tool's outputSample for a concrete example.",
"items": {
"type": "object"
},
"type": "array"
},
"payment": {
"description": "Settlement summary (protocol, amount, currency).",
"type": "object"
},
"runId": {
"description": "Run ID for debugging/audit.",
"type": "string"
}
},
"required": [
"items"
],
"type": "object"
},
"type": {
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
}
},
"required": [
"input"
],
"type": "object"
},
"tags": [
"twitter",
"x",
"timeline",
"user-tweets",
"feed",
"replies",
"quotes",
"retweeters",
"mentions",
"history",
"social",
"agent",
"x402"
]
},
"eip2612GasSponsoring": {
"info": {
"description": "The facilitator accepts EIP-2612 gasless Permit to `Permit2` canonical contract.",
"version": "1"
},
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"amount": {
"description": "The amount to approve (uint256). Typically MaxUint.",
"pattern": "^[0-9]+$",
"type": "string"
},
"asset": {
"description": "The address of the ERC-20 token contract.",
"pattern": "^0x[a-fA-F0-9]{40}$",
"type": "string"
},
"deadline": {
"description": "The timestamp at which the signature expires.",
"pattern": "^[0-9]+$",
"type": "string"
},
"from": {
"description": "The address of the sender.",
"pattern": "^0x[a-fA-F0-9]{40}$",
"type": "string"
},
"nonce": {
"description": "The current nonce of the sender.",
"pattern": "^[0-9]+$",
"type": "string"
},
"signature": {
"description": "The 65-byte concatenated signature (r, s, v) as a hex string.",
"pattern": "^0x[a-fA-F0-9]+$",
"type": "string"
},
"spender": {
"description": "The address of the spender (Canonical Permit2).",
"pattern": "^0x[a-fA-F0-9]{40}$",
"type": "string"
},
"version": {
"description": "Schema version identifier.",
"pattern": "^[0-9]+(\\.[0-9]+)*$",
"type": "string"
}
},
"required": [
"from",
"asset",
"spender",
"amount",
"nonce",
"deadline",
"signature",
"version"
],
"type": "object"
}
}
}Use it
curl
curl "https://twitr.sh/api/tools/x_timeline" # -> 402 Payment Required, accepts[] lists how to pay # retry with a PAYMENT-SIGNATURE (or PAYMENT header) once paid
JavaScript
const res = await fetch("https://twitr.sh/api/tools/x_timeline");
if (res.status === 402) {
const { accepts } = await res.json();
// pay one of accepts[] via an x402 client, then retry with the payment header
}Python
import httpx
res = httpx.get("https://twitr.sh/api/tools/x_timeline")
if res.status_code == 402:
accepts = res.json()["accepts"]
# pay one of accepts[] via an x402 client, then retry with the payment headerMachine-readable
Everything on this page is also available as clean JSON at /resources/4336.json, and this resource appears in /discovery/resources and /discovery/search.