{"openapi":"3.1.0","info":{"title":"ReadX — X/Twitter JSON API","version":"1.0.0","description":"Read-only Twitter/X data as JSON, paid per call via x402 micropayments (USDC on Base or Solana). No X login required.","x-guidance":"Read-only X (Twitter) data as JSON, paid per call with x402 (USDC on Base or Solana, default $0.01 per request). To check liveness/connectivity, call GET /api/health (free, no parameters) rather than a data endpoint with its literal {name}/{id} placeholder still in place - those are real routes matched by any value, so an unsubstituted placeholder just returns a normal 404 for a nonexistent user/tweet. Every other endpoint is a GET under /api. Use GET /api/{name}/profile for a user's profile (user object, photo rail, pinned tweet), GET /api/{name} for their timeline (also /api/{name}/with_replies and /api/{name}/with_media), GET /api/{name}/about for account info, GET /api/{name}/followers and GET /api/{name}/followers_web to export a user's followers (~200 per page and web-visible ~70 per page capped at ~800; paginate with ?cursor= using pagination.next_cursor until pagination.has_more is false), GET /api/{name}/following and GET /api/{name}/following_web for following lists (same page sizes), GET /api/{name}/verified_followers for verified followers only, GET /api/{name}/mentions for tweets that mention a user, GET /api/{name}/media for a user's tweets that contain media (~20 per page), GET /api/{name}/affiliates for accounts affiliated with a user, GET /api/{name}/relations?name=... to check whether one user follows another (plus block/mute/DM flags), GET /api/{name}/info for a user's profile info (id, name, bio, location, follower/following counts, verification), GET /api/trends for a location's trending topics (worldwide by default; filter with ?country= or ?woeid=), GET /api/spaces/{id} for a Space's metadata (title, host, state, listener counts, downloadable), GET /api/{name}/tweets/{id} for a tweet and its conversation (or GET /api/tweets/{id} for just the tweet, GET /api/{name}/tweets/{id}/history for its edit history, GET /api/tweets/{id}/replies for its replies, and GET /api/tweets/{id}/retweeters for accounts that retweeted it), GET /api/search?q=... for search (a leading @ or an f:user filter returns users instead of tweets), GET /api/search/users?q=... to search for users, and GET /api/search/tweets?q=... to search for tweets. Read the members of an X List via /api/lists/{id}/members; resolve an @handle to a user id with /api/tools/get_user_id?username=... (or up to 20 at once with /api/tools/get_user_ids?usernames=...), or a numeric user id to a username with /api/tools/get_username?user_id=... (or up to 20 at once with /api/tools/get_usernames?user_ids=...). Paginate any endpoint by passing a response's pagination.next_cursor back as ?cursor= until pagination.has_more is false (the conversation endpoint at /api/{name}/tweets/{id} instead carries its own nested before/after/replies cursors, described on that endpoint). Endpoints wrap data as { code: 0, data: ..., pagination: ... } on success (pagination present when the endpoint paginates) and { code: -1, error, error_type } on error.","contact":{"email":"hey@readx.sh"}},"servers":[{"url":"https://readx.sh"}],"externalDocs":{"description":"Agent skill — drop-in skill file describing every endpoint and the x402 payment flow.","url":"https://readx.sh/skill.md"},"tags":[{"name":"System"},{"name":"Profiles"},{"name":"Tweets"},{"name":"Search"},{"name":"Hashtags"},{"name":"Lists"},{"name":"Trends"},{"name":"Spaces"},{"name":"Broadcasts"},{"name":"Articles"},{"name":"Tools"}],"paths":{"/api/health":{"get":{"operationId":"getHealth","summary":"Liveness check - confirms the service is reachable","description":"Free, unauthenticated, no path or query parameters. Use this to check connectivity or uptime instead of calling a data endpoint with its literal `{name}`/`{id}` placeholder still in place - those are real routes and a placeholder value returns a normal 404, not a liveness signal.","tags":["System"],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"OK"}}}}}}},"/api/{name}":{"get":{"operationId":"getUserTimeline","summary":"User timeline - tweets for an X handle","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Timeline of tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"},"example":{"code":0,"data":{"timeline":[{"id":"20","threadId":"20","replyId":"0","user":{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":4000,"followers":6500000,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214},"text":"just setting up my twttr","time":1142974214,"reply":[],"pinned":false,"hasThread":false,"available":true,"tombstone":"","location":"","source":"","stats":{"replies":200000,"retweets":130000,"likes":200000,"quotes":9000,"views":0},"retweet":null,"attribution":null,"mediaTags":null,"quote":null,"card":null,"poll":null,"media":null,"history":null,"note":null,"isAd":false,"isAI":false}]},"pagination":{"has_more":true,"is_first_page":true,"next_cursor":"DAABCgAB...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/with_replies":{"get":{"operationId":"getUserTimelineWithReplies","summary":"User timeline including replies","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Timeline of tweets and replies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/with_media":{"get":{"operationId":"getUserMedia","summary":"User media timeline","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Timeline of media tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/profile":{"get":{"operationId":"getUserProfile","summary":"User profile - user object, photo rail, and pinned tweet","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"},"example":{"code":0,"data":{"user":{"id":"12","username":"jack","fullname":"jack","bio":"","followers":6500000,"following":4000,"tweets":30000,"verifiedType":"Blue","joinDate":1142974214},"photoRail":[],"pinned":null}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."}},"required":["name"]}}}}}},"/api/{name}/about":{"get":{"operationId":"getUserAbout","summary":"Account info - join date, location, verification","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Account info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AboutResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."}},"required":["name"]}}}}}},"/api/{name}/pinned":{"get":{"operationId":"getUserPinnedTweet","summary":"The user's pinned tweet","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The pinned tweet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinnedResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."}},"required":["name"]}}}}}},"/api/{name}/followers":{"get":{"operationId":"getUserFollowers","summary":"A user's followers (~200 per page)","tags":["Profiles"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of followers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":4000,"followers":6500000,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}],"total_count":200},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/followers_web":{"get":{"operationId":"getUserFollowersWeb","summary":"A user's followers as shown on the web (~70 per page, capped at ~800)","tags":["Profiles"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false. Capped at ~800 results total.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of web-visible followers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":4000,"followers":6500000,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}],"total_count":70},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/following":{"get":{"operationId":"getUserFollowing","summary":"Accounts a user follows (~200 per page)","tags":["Profiles"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of following accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":4000,"followers":6500000,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}],"total_count":200},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/following_web":{"get":{"operationId":"getUserFollowingWeb","summary":"Accounts a user follows as shown on the web (~70 per page, capped at ~800)","tags":["Profiles"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false. Capped at ~800 results total.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of web-visible following accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":4000,"followers":6500000,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}],"total_count":70},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/verified_followers":{"get":{"operationId":"getUserVerifiedFollowers","summary":"A user's verified followers (~200 per page)","tags":["Profiles"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of verified followers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":4000,"followers":6500000,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}],"total_count":200},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/mentions":{"get":{"operationId":"getUserMentions","summary":"Tweets that mention a user","tags":["Profiles"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of tweets mentioning the user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TweetsListResponse"},"example":{"code":0,"data":{"tweets":[{"id":"21","threadId":"20","replyId":"0","user":{"id":"99","username":"someone","fullname":"Someone","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":307,"followers":599,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214},"text":"@jack hello","time":1142974214,"reply":[],"pinned":false,"hasThread":false,"available":true,"tombstone":"","location":"","source":"","stats":{"replies":0,"retweets":0,"likes":42,"quotes":0,"views":0},"retweet":null,"attribution":null,"mediaTags":null,"quote":null,"card":null,"poll":null,"media":null,"history":null,"note":null,"isAd":false,"isAI":false}]},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/media":{"get":{"operationId":"getUserMediaTweets","summary":"A user's tweets that contain media","tags":["Profiles"],"description":"Tweets containing photos, videos, or GIFs (~20 per page). Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of the user's media tweets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TweetsListResponse"},"example":{"code":0,"data":{"tweets":[{"id":"2081338409260400913","threadId":"2081338409260400913","replyId":"0","user":{"id":"12","username":"jack","fullname":"jack","location":"","website":"http://primal.net/jack","bio":"no state is the best state","userPic":"https://pbs.twimg.com/profile_images/1661201415899951105/azNjKOSH.jpg","banner":"https://pbs.twimg.com/profile_banners/12/1742427520","pinnedTweet":"1833951636005552366","following":3,"followers":10514470,"tweets":30783,"likes":39905,"media":2973,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214},"text":"https://t.co/tZ7YRJYWrL","time":1785064720,"reply":[],"pinned":false,"hasThread":false,"available":true,"tombstone":"","location":"","source":"Twitter Web App","stats":{"replies":153,"retweets":186,"likes":3797,"quotes":40,"views":0},"retweet":null,"attribution":null,"mediaTags":null,"quote":null,"card":null,"poll":null,"media":[{"type":"photo","url":"https://pbs.twimg.com/media/HOJmNdSXkAE_Ksq.jpg","altText":""}],"history":null,"note":null,"isAd":false,"isAI":false}],"total_count":20},"pagination":{"has_more":true,"next_cursor":"DAABCgABHAYpKoW___0..."}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name"]}}}}}},"/api/{name}/affiliates":{"get":{"operationId":"getUserAffiliates","summary":"Accounts affiliated with a user","tags":["Profiles"],"description":"Accounts affiliated with the user (e.g. an organization's members).","parameters":[{"$ref":"#/components/parameters/Name"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Affiliated accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":4000,"followers":6500000,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}],"total_count":3}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."}},"required":["name"]}}}}}},"/api/{name}/relations":{"get":{"operationId":"getUserRelations","summary":"Follow relationship between two users","tags":["Profiles"],"description":"Check whether the path user follows the query `name` user, and whether the reverse follow, block, mute, or DM eligibility flags apply. Path `{name}` is the source handle; query `name` is the target handle.","parameters":[{"$ref":"#/components/parameters/Name"},{"name":"name","in":"query","required":true,"description":"Target X handle without the leading @ (alphanumeric and underscore).","schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$"}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The follow relationship and related flags between the two users. A single entity, not a paginated list — no `pagination` field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationsResponse"},"example":{"code":0,"data":{"source":"jack","target":"elonmusk","sourceFollowsTarget":true,"targetFollowsSource":false,"canDm":false,"blocking":false,"blockedBy":false,"muting":false}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"Target X handle without the leading @ (alphanumeric and underscore)."}},"required":["name","name"]}}}}}},"/api/{name}/info":{"get":{"operationId":"getUserInfo","summary":"A user's profile info","tags":["Profiles"],"description":"Id, name, bio, location, follower/following counts, and verification status.","parameters":[{"$ref":"#/components/parameters/Name"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The user's profile info. A single entity, not a paginated list — no `pagination` field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"},"example":{"code":0,"data":{"id":"12","username":"jack","fullname":"jack","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"1833951636005552366","following":4000,"followers":6500000,"tweets":30715,"likes":39744,"media":2968,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."}},"required":["name"]}}}}}},"/api/tools/get_user_id":{"get":{"operationId":"resolveHandle","summary":"Resolve an @handle to a numeric user id","tags":["Tools"],"parameters":[{"name":"username","in":"query","required":true,"description":"The @handle, without the @ (alphanumeric and underscore).","schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$"}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The resolved user id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserIdResponse"},"example":{"code":0,"data":{"id":"12"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"The @handle, without the @ (alphanumeric and underscore)."}},"required":["username"]}}}}}},"/api/tweets/{id}":{"get":{"operationId":"getTweetOnly","summary":"A single tweet (without its conversation)","tags":["Tweets"],"parameters":[{"$ref":"#/components/parameters/TweetId"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A single tweet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TweetResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."}},"required":["id"]}}}}}},"/api/{name}/tweets/{id}":{"get":{"operationId":"getTweet","summary":"A tweet and its conversation (before/after/replies)","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/TweetId"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A tweet and its conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["name","id"]}}}}}},"/api/{name}/tweets/{id}/history":{"get":{"operationId":"getTweetEditHistory","summary":"A tweet's edit history (latest plus prior versions)","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/TweetId"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The tweet's edit history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditHistoryResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."}},"required":["name","id"]}}}}}},"/api/tweets/{id}/replies":{"get":{"operationId":"getTweetReplies","summary":"Replies to a tweet","tags":["Tweets"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/TweetId"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of replies to the tweet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TweetsListResponse"},"example":{"code":0,"data":{"tweets":[{"id":"21","threadId":"20","replyId":"0","user":{"id":"99","username":"someone","fullname":"Someone","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":307,"followers":599,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214},"text":"great point","time":1142974214,"reply":[],"pinned":false,"hasThread":false,"available":true,"tombstone":"","location":"","source":"","stats":{"replies":0,"retweets":0,"likes":3,"quotes":0,"views":0},"retweet":null,"attribution":null,"mediaTags":null,"quote":null,"card":null,"poll":null,"media":null,"history":null,"note":null,"isAd":false,"isAI":false}]},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["id"]}}}}}},"/api/tweets/{id}/retweeters":{"get":{"operationId":"getTweetRetweeters","summary":"Accounts that retweeted a tweet","tags":["Tweets"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/TweetId"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of accounts that retweeted the tweet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"99","username":"someone","fullname":"Someone","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":307,"followers":599,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}],"total_count":200},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["id"]}}}}}},"/api/search/users":{"get":{"operationId":"searchUsers","summary":"Search for users by query","tags":["Search"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"name":"q","in":"query","required":true,"description":"User search query (matches handles, names and bios).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of users matching the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"99","username":"someone","fullname":"Someone","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":307,"followers":599,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214}]},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"description":"User search query (matches handles, names and bios)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["q"]}}}}}},"/api/search/tweets":{"get":{"operationId":"searchTweets","summary":"Search for tweets by query","tags":["Search"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"name":"q","in":"query","required":true,"description":"Tweet search query.","schema":{"type":"string","minLength":1}},{"name":"product","in":"query","required":false,"description":"Result ordering, e.g. Top or Latest.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of tweets matching the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TweetsListResponse"},"example":{"code":0,"data":{"tweets":[{"id":"22","threadId":"20","replyId":"0","user":{"id":"99","username":"someone","fullname":"Someone","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":307,"followers":599,"tweets":30000,"likes":0,"media":0,"verifiedType":"Blue","protected":false,"suspended":false,"joinDate":1142974214},"text":"... typescript ...","time":1142974214,"reply":[],"pinned":false,"hasThread":false,"available":true,"tombstone":"","location":"","source":"","stats":{"replies":0,"retweets":0,"likes":42,"quotes":0,"views":0},"retweet":null,"attribution":null,"mediaTags":null,"quote":null,"card":null,"poll":null,"media":null,"history":null,"note":null,"isAd":false,"isAI":false}]},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"description":"Tweet search query."},"product":{"type":"string","description":"Result ordering, e.g. Top or Latest."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["q"]}}}}}},"/api/search":{"get":{"operationId":"search","summary":"Search tweets (or users for @ / f:user queries)","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query (max 500 chars). A leading @ or an f:user filter returns users instead of tweets.","schema":{"type":"string","minLength":1,"maxLength":500}},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Tweet results, or user results for @ / f:user queries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":500,"description":"Search query (max 500 chars). A leading @ or an f:user filter returns users instead of tweets."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["q"]}}}}}},"/api/hashtag/{tag}":{"get":{"operationId":"getHashtag","summary":"Resolve a hashtag to its tweet search","tags":["Hashtags"],"parameters":[{"name":"tag","in":"path","required":true,"description":"Hashtag without the leading #.","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Tweet search results for the hashtag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string","minLength":1,"description":"Hashtag without the leading #."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["tag"]}}}}}},"/api/lists/{id}/members":{"get":{"operationId":"getListMembers","summary":"Members of a List","tags":["Lists"],"description":"Paginate by passing pagination.next_cursor from the response as ?cursor= until pagination.has_more is false.","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A page of list members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersListResponse"},"example":{"code":0,"data":{"users":[{"id":"12","username":"someone","fullname":"Someone","location":"","website":"","bio":"","userPic":"","banner":"","pinnedTweet":"0","following":0,"followers":0,"tweets":0,"likes":0,"media":0,"verifiedType":"None","protected":false,"suspended":false,"joinDate":0}],"total_count":20},"pagination":{"has_more":true,"next_cursor":"DAABCgABG...cursor"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$","description":"Numeric resource id."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint)."}},"required":["id"]}}}}}},"/api/trends":{"get":{"operationId":"getTrends","summary":"Trending topics for a location","tags":["Trends"],"description":"Worldwide trends by default; filter with country (name or ISO code) or woeid (overrides country when both are given).","parameters":[{"name":"country","in":"query","required":false,"description":"Location name (country/city) or ISO code, e.g. US, india, tokyo.","schema":{"type":"string"}},{"name":"woeid","in":"query","required":false,"description":"Numeric Yahoo WOEID, e.g. 1 for worldwide, 23424977 for the USA. Overrides country when both are given.","schema":{"type":"string"}},{"name":"count","in":"query","required":false,"description":"Cap the number of trends returned (up to 50).","schema":{"type":"integer","minimum":1,"maximum":50}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The location's current trending topics, ranked.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","additionalProperties":true,"description":"Trend fields vary by location and aren't schema-typed to a fixed shape — see the example for the fields to expect."}},"required":["code","data"]},"example":{"code":0,"data":{"status":"success","woeid":23424977,"location":"United States","as_of":"2026-07-25T04:51:10Z","trends_count":2,"trends":[{"rank":1,"name":"#TypeScript","is_hashtag":true,"tweet_volume":18452,"query":"#TypeScript","search_url":"https://x.com/search?q=%23TypeScript&src=trend_click","promoted":false},{"rank":2,"name":"Cloudflare","is_hashtag":false,"tweet_volume":null,"query":"Cloudflare","search_url":"https://x.com/search?q=Cloudflare&src=trend_click","promoted":false}]}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"Location name (country/city) or ISO code, e.g. US, india, tokyo."},"woeid":{"type":"string","description":"Numeric Yahoo WOEID, e.g. 1 for worldwide, 23424977 for the USA. Overrides country when both are given."},"count":{"type":"integer","minimum":1,"maximum":50,"description":"Cap the number of trends returned (up to 50)."}}}}}}}},"/api/tools/get_username":{"get":{"operationId":"resolveUserId","summary":"Resolve a numeric user id to a username","tags":["Tools"],"parameters":[{"name":"user_id","in":"query","required":true,"description":"The numeric user id.","schema":{"type":"string","pattern":"^[0-9]+$"}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The resolved username","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameResponse"},"example":{"code":0,"data":{"username":"jack"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","pattern":"^[0-9]+$","description":"The numeric user id."}},"required":["user_id"]}}}}}},"/api/spaces/{id}":{"get":{"operationId":"getSpaceInfo","summary":"A Space's metadata by id","tags":["Spaces"],"description":"Title, host, state, listener counts, and whether the Space's audio is downloadable. The id is the segment after `/i/spaces/` in a Space URL.","parameters":[{"name":"id","in":"path","required":true,"description":"The Space id (alphanumeric; the segment after `/i/spaces/` in a Space URL).","schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9]+$"}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The Space's metadata. A single entity, not a paginated list — no `pagination` field.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","additionalProperties":true,"description":"Space fields — see the example for the fields to expect."}},"required":["code","data"]},"example":{"code":0,"data":{"space_id":"1vOxwrneqBqJB","title":"The @BorderlandsFilm cast is live with @Fandango at SDCC!","state":"Ended","host_username":"Movies","host_name":"Movies","started_at":"2024-07-26T23:31:16.881Z","ended_at":"2024-07-27T00:09:14.898Z","is_live":false,"is_replay_available":true,"total_live_listeners":465,"total_replay_watched":59649,"stream_type":"replay","downloadable":true}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9]+$","description":"The Space id (alphanumeric; the segment after `/i/spaces/` in a Space URL)."}},"required":["id"]}}}}}},"/api/broadcasts/{id}":{"get":{"operationId":"getBroadcast","summary":"A broadcast by id","tags":["Broadcasts"],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$","description":"Numeric resource id."}},"required":["id"]}}}}}},"/api/article-entities/{article_id}":{"get":{"operationId":"getArticleEntity","summary":"An X article by entity rest_id (owner-only)","tags":["Articles"],"description":"Requires the article owner's `auth_token`.","parameters":[{"$ref":"#/components/parameters/ArticleEntityId"},{"$ref":"#/components/parameters/AuthToken"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The article payload.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","additionalProperties":true,"description":"Article fields vary by result and aren't schema-typed to a fixed shape."}},"required":["code","data"]}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"article_id":{"type":"string","minLength":1,"description":"The article entity rest_id."},"auth_token":{"type":"string","minLength":1,"description":"The article owner's X auth_token cookie value (required for entity rest_id lookups)."}},"required":["article_id","auth_token"]}}}}}},"/api/articles/{id}":{"get":{"operationId":"getArticle","summary":"An X article by wrapper tweet id (public)","tags":["Articles"],"description":"An X article (long-form post) by its wrapper tweet id.","parameters":[{"$ref":"#/components/parameters/ArticleId"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The article payload.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","additionalProperties":true,"description":"Article fields vary by result and aren't schema-typed to a fixed shape."}},"required":["code","data"]},"example":{"code":0,"data":{"status":"success","msg":"success","article":{"id":"QXJ0aWNsZUVudGl0eToyMDM4OTk4NDgzNDQxNDc5Njgw","author":{"type":"user","userName":"jack","url":"https://x.com/jack","twitterUrl":"https://twitter.com/jack","id":"12","name":"jack","isVerified":false,"isBlueVerified":true,"verifiedType":null,"profilePicture":"https://pbs.twimg.com/profile_images/1661201415899951105/azNjKOSH_normal.jpg","coverPicture":"https://pbs.twimg.com/profile_banners/12/1742427520","description":"no state is the best state","location":"","followers":10342967,"following":3,"canDm":true,"createdAt":"Tue Mar 21 20:50:14 +0000 2006","favouritesCount":39746,"statusesCount":30715,"mediaCount":2968,"pinnedTweetIds":["1833951636005552366"]},"replyCount":567,"likeCount":11056,"quoteCount":789,"viewCount":6451994,"createdAt":"Tue Mar 31 15:36:22 +0000 2026","title":"From Hierarchy to Intelligence","preview_text":"At Sequoia, we see that speed is the best predictor of start-up success. Most companies are focused on AI as a productivity enhancer. Few are focused on the potential of AI to change how we work","cover_media_img_url":"https://pbs.twimg.com/media/HEv7_K5WIAEcknc.jpg","contents":[{"type":"unstyled","text":"At Sequoia, we see that speed is the best predictor of start-up success. Most companies are focused on AI as a productivity enhancer. Few are focused on the potential of AI to change how we work together. Block is showing what it looks like to fundamentally rethink organization design, ultimately harnessing AI to increase speed as a compounding competitive advantage."},{"type":"unstyled","text":"Two thousand years before the first corporate org chart, the Roman Army solved a problem that every large organization still faces: how do you coordinate thousands of people across vast distances with limited communication?"}]}}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The wrapper tweet id for the article (public lookup)."}},"required":["id"]}}}}}},"/api/tools/get_user_ids":{"get":{"operationId":"resolveHandles","summary":"Resolve up to 20 @handles to numeric user ids","description":"Accepts a comma-separated list of up to 20 @handles. Returns a map of handle to user id. A failed lookup for one handle sets that entry to null and does not fail the rest.","tags":["Tools"],"parameters":[{"name":"usernames","in":"query","required":true,"description":"Comma-separated @handles, without the @ (alphanumeric and underscore). At most 20.","schema":{"type":"string","minLength":1}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Map of handle → user id (null when that lookup failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserIdsResponse"},"example":{"code":0,"data":{"jack":"12","elonmusk":"44196397","thisuserdoesnotexistzzz":null}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"usernames":{"type":"string","minLength":1,"description":"Comma-separated @handles, without the @ (alphanumeric and underscore). At most 20."}},"required":["usernames"]}}}}}},"/api/tools/get_usernames":{"get":{"operationId":"resolveUserIds","summary":"Resolve up to 20 numeric user ids to usernames","description":"Accepts a comma-separated list of up to 20 numeric user ids. Returns a map of user id to username. A failed lookup for one id sets that entry to null and does not fail the rest.","tags":["Tools"],"parameters":[{"name":"user_ids","in":"query","required":true,"description":"Comma-separated numeric user ids. At most 20.","schema":{"type":"string","minLength":1}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Map of user id → username (null when that lookup failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernamesResponse"},"example":{"code":0,"data":{"0":null,"12":"jack","44196397":"elonmusk"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"string","minLength":1,"description":"Comma-separated numeric user ids. At most 20."}},"required":["user_ids"]}}}}}}},"components":{"parameters":{"Name":{"name":"name","in":"path","required":true,"description":"X handle without the leading @ (alphanumeric and underscore).","schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$"}},"TweetId":{"name":"id","in":"path","required":true,"description":"Numeric tweet id (up to 19 digits).","schema":{"type":"string","pattern":"^[0-9]{1,19}$"}},"ResourceId":{"name":"id","in":"path","required":true,"description":"Numeric resource id.","schema":{"type":"string","pattern":"^[0-9]+$"}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response's pagination.next_cursor (the conversation endpoint at /api/{name}/tweets/{id} instead takes its own nested reply cursor — see that endpoint).","schema":{"type":"string"}},"ArticleId":{"name":"id","in":"path","required":true,"description":"The wrapper tweet id for the article (public lookup).","schema":{"type":"string","minLength":1}},"ArticleEntityId":{"name":"article_id","in":"path","required":true,"description":"The article entity rest_id.","schema":{"type":"string","minLength":1}},"AuthToken":{"name":"auth_token","in":"query","required":true,"description":"The article owner's X auth_token cookie value (required for entity rest_id lookups).","schema":{"type":"string","minLength":1}}},"schemas":{"User":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"fullname":{"type":"string"},"location":{"type":"string"},"website":{"type":"string"},"bio":{"type":"string"},"userPic":{"type":"string"},"banner":{"type":"string"},"pinnedTweet":{"type":"string","description":"Id of the pinned tweet, or \"0\" when absent."},"following":{"type":"integer"},"followers":{"type":"integer"},"tweets":{"type":"integer"},"likes":{"type":"integer"},"media":{"type":"integer"},"verifiedType":{"type":"string","enum":["None","Blue","Business","Government"]},"protected":{"type":"boolean"},"suspended":{"type":"boolean"},"joinDate":{"type":"integer","description":"Unix timestamp (seconds)."}}},"TweetStats":{"type":"object","properties":{"replies":{"type":"integer"},"retweets":{"type":"integer"},"likes":{"type":"integer"},"quotes":{"type":"integer"},"views":{"type":"integer"}}},"Media":{"type":"object","properties":{"type":{"type":"string","enum":["photo","video","gif"]},"url":{"type":"string"},"thumb":{"type":"string"},"altText":{"type":"string"},"durationMs":{"type":"integer"},"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string"},"url":{"type":"string"},"bitrate":{"type":"integer"},"resolution":{"type":"string"}}}}},"required":["type"]},"TweetSummary":{"type":"object","description":"A tweet without its own nested retweet/quote (used for nested retweet/quote to keep the schema acyclic).","properties":{"id":{"type":"string"},"threadId":{"type":"string"},"replyId":{"type":"string"},"user":{"$ref":"#/components/schemas/User"},"text":{"type":"string"},"time":{"type":"integer","description":"Unix timestamp (seconds)."},"reply":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean"},"hasThread":{"type":"boolean"},"available":{"type":"boolean"},"tombstone":{"type":"string"},"location":{"type":"string"},"source":{"type":"string"},"stats":{"$ref":"#/components/schemas/TweetStats"},"attribution":{"anyOf":[{"$ref":"#/components/schemas/User"},{"type":"null"}]},"mediaTags":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/User"}},{"type":"null"}]},"card":{"type":["object","null"]},"poll":{"type":["object","null"]},"media":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Media"}},{"type":"null"}]},"history":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"note":{"type":["string","null"]},"isAd":{"type":"boolean"},"isAI":{"type":"boolean"}}},"Tweet":{"type":"object","properties":{"id":{"type":"string"},"threadId":{"type":"string"},"replyId":{"type":"string"},"user":{"$ref":"#/components/schemas/User"},"text":{"type":"string"},"time":{"type":"integer","description":"Unix timestamp (seconds)."},"reply":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean"},"hasThread":{"type":"boolean"},"available":{"type":"boolean"},"tombstone":{"type":"string"},"location":{"type":"string"},"source":{"type":"string"},"stats":{"$ref":"#/components/schemas/TweetStats"},"retweet":{"anyOf":[{"$ref":"#/components/schemas/TweetSummary"},{"type":"null"}]},"attribution":{"anyOf":[{"$ref":"#/components/schemas/User"},{"type":"null"}]},"mediaTags":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/User"}},{"type":"null"}]},"quote":{"anyOf":[{"$ref":"#/components/schemas/TweetSummary"},{"type":"null"}]},"card":{"type":["object","null"]},"poll":{"type":["object","null"]},"media":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Media"}},{"type":"null"}]},"history":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"note":{"type":["string","null"]},"isAd":{"type":"boolean"},"isAI":{"type":"boolean"}}},"Pagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string"},"is_first_page":{"type":"boolean"},"top_cursor":{"type":"string"}},"required":["has_more"]},"AccountInfo":{"type":"object","properties":{"username":{"type":"string"},"fullname":{"type":"string"},"userPic":{"type":"string"},"joinDate":{"type":"integer","description":"Unix timestamp (seconds)."},"verifiedType":{"type":"string","enum":["None","Blue","Business","Government"]},"suspended":{"type":"boolean"},"basedIn":{"type":"string"},"source":{"type":"string"},"usernameChanges":{"type":"integer"},"lastUsernameChange":{"type":"integer"},"affiliateUsername":{"type":"string"},"affiliateLabel":{"type":"string"},"isIdentityVerified":{"type":"boolean"},"verifiedSince":{"type":"integer"},"overrideVerifiedYear":{"type":"integer"}}},"Broadcast":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"state":{"type":"string"},"thumb":{"type":"string"},"mediaKey":{"type":"string"},"m3u8Url":{"type":"string"},"totalWatched":{"type":"integer"},"startTime":{"type":"integer"},"endTime":{"type":"integer"},"replayStart":{"type":"integer"},"availableForReplay":{"type":"boolean"},"user":{"$ref":"#/components/schemas/User"}}},"TimelineData":{"type":"object","description":"The `data` payload for a paginated timeline/search-tweets route. Pagination itself is a sibling of `data` at the envelope root (see `Pagination`), not nested here.","properties":{"timeline":{"type":"array","description":"Tweets, with threads represented as nested arrays of tweets.","items":{"anyOf":[{"$ref":"#/components/schemas/Tweet"},{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}}]}},"pinned":{"anyOf":[{"$ref":"#/components/schemas/Tweet"},{"type":"null"}],"description":"Present only on the first page of `/api/{name}` and `/api/{name}/with_replies`. `/api/{name}/with_media` may omit it."}},"required":["timeline"]},"UsersData":{"type":"object","description":"The `data` payload for a route returning a list of users. Pagination itself is a sibling of `data` at the envelope root (see `Pagination`), not nested here.","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"total_count":{"type":"integer","description":"Total number of matching users, when the endpoint reports one."}},"required":["users"]},"TweetsData":{"type":"object","description":"The `data` payload for a route returning a list of tweets. Pagination itself is a sibling of `data` at the envelope root (see `Pagination`), not nested here.","properties":{"tweets":{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}},"total_count":{"type":"integer","description":"Total number of matching tweets, when the endpoint reports one."}},"required":["tweets"]},"ProfileData":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"photoRail":{"type":"array","items":{"type":"object"}},"pinned":{"anyOf":[{"$ref":"#/components/schemas/Tweet"},{"type":"null"}]}},"required":["user"]},"ConversationData":{"type":"object","properties":{"tweet":{"$ref":"#/components/schemas/Tweet"},"before":{"type":"object","properties":{"tweets":{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}}}},"after":{"type":"object","properties":{"tweets":{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}},"hasMore":{"type":"boolean"},"cursor":{"type":"string"}}},"replies":{"type":"object","properties":{"beginning":{"type":"boolean"},"top":{"type":"string"},"bottom":{"type":"string"},"tweets":{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}}}}},"required":["tweet"]},"TimelineResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/TimelineData"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["code","data"]},"UsersListResponse":{"type":"object","description":"Response envelope for a route returning a page of users. `pagination` is present whenever the route paginates.","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/UsersData"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["code","data"]},"TweetsListResponse":{"type":"object","description":"Response envelope for a route returning a page of tweets. `pagination` is present whenever the route paginates.","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/TweetsData"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["code","data"]},"UserResponse":{"type":"object","description":"Response envelope for a single-entity user route (e.g. /api/{name}/info). Not paginated, so no `pagination` field.","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/User"}},"required":["code","data"]},"RelationsData":{"type":"object","description":"Follow relationship between a source and target user, plus related block/mute/DM flags.","properties":{"source":{"type":"string","description":"Source @handle (the path `{name}`)."},"target":{"type":"string","description":"Target @handle (the query `name`)."},"sourceFollowsTarget":{"type":"boolean","description":"True if source follows target."},"targetFollowsSource":{"type":"boolean","description":"True if target follows source."},"canDm":{"type":"boolean","description":"True if source can DM target."},"blocking":{"type":"boolean","description":"True if source is blocking target."},"blockedBy":{"type":"boolean","description":"True if source is blocked by target."},"muting":{"type":"boolean","description":"True if source is muting target."}},"required":["source","target","sourceFollowsTarget","targetFollowsSource","canDm","blocking","blockedBy","muting"]},"RelationsResponse":{"type":"object","description":"Response envelope for /api/{name}/relations. Not paginated, so no `pagination` field.","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/RelationsData"}},"required":["code","data"]},"SearchResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"anyOf":[{"$ref":"#/components/schemas/TimelineData"},{"$ref":"#/components/schemas/UsersData"}]},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["code","data"]},"ProfileResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/ProfileData"}},"required":["code","data"]},"AboutResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/AccountInfo"}},"required":["code","data"]},"PinnedResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/Tweet"}},"required":["code","data"]},"ConversationResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/ConversationData"}},"required":["code","data"]},"UsernameResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"]}},"required":["code","data"]},"UserIdResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["code","data"]},"BroadcastResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/Broadcast"}},"required":["code","data"]},"TweetResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/Tweet"}},"required":["code","data"]},"EditHistory":{"type":"object","properties":{"latest":{"$ref":"#/components/schemas/Tweet"},"history":{"type":"array","description":"Prior versions of the tweet, oldest to newest.","items":{"$ref":"#/components/schemas/Tweet"}}},"required":["latest","history"]},"EditHistoryResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/EditHistory"}},"required":["code","data"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","const":-1},"error":{"type":"string"},"error_type":{"type":"string"}},"required":["code","error"]},"UserIdsResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","additionalProperties":{"type":["string","null"]},"description":"Map of @handle → numeric user id, or null when that lookup failed."}},"required":["code","data"]},"UsernamesResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","additionalProperties":{"type":["string","null"]},"description":"Map of numeric user id → @username, or null when that lookup failed."}},"required":["code","data"]}}}}