Back to Details

x-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

X (Twitter) Data API

X (Twitter) 数据API

A drop-in X data source for agents: search posts, resolve profiles, pull timelines and followers, read Lists, and check trends — all as one plain HTTP GET, paid per call. No developer account, no app review, no OAuth handshake, and no waiting on X's own API tiers or rate-limit approvals. If your task mentions an X search query, a handle, a post/tweet ID, or a list ID, this is the skill.
Base URL: 
https://twitter.fetcher.sh
— the API host is still named 
twitter
(it predates the rebrand and matches what agents already search for); everything below is current X data.
Also published as 
twitter-api
 — identical endpoints, indexed under the "Twitter" name too since both are still in everyday use.
为Agent提供即插即用的X数据源：搜索帖子、解析个人资料、获取时间线和关注者、查看列表、查询热门话题——所有操作均通过简单的HTTP GET请求完成，按调用付费。无需开发者账号、无需应用审核、无需OAuth握手，也无需等待X官方API的层级或速率限制审批。如果你的任务涉及X搜索查询、用户名、帖子/推文ID或列表ID，那么这个skill正是你需要的。
基础URL：
https://twitter.fetcher.sh
——API主机仍命名为
twitter
（早于品牌更名，且与Agent已搜索的内容匹配）；以下所有内容均为最新的X数据。
同时也以
twitter-api
发布——端点完全相同，也以"Twitter"名称索引，因为两者仍在日常使用中。

Quick reference

快速参考

Base URL
https://twitter.fetcher.sh
Auth
Authorization: Bearer bby_live_...
or x402 (USDC)
Price$0.002–$0.005/call
Endpoints15, all 
GET
MCP
https://twitter.fetcher.sh/mcp
Machine-readable
/openapi.json
· 
/llms.txt
· 
/skill.md
基础URL
https://twitter.fetcher.sh
认证方式
Authorization: Bearer bby_live_...
或 x402（USDC）
价格$0.002–$0.005/次调用
端点数量15个，均为
GET
请求
MCP
https://twitter.fetcher.sh/mcp
机器可读资源
/openapi.json
· 
/llms.txt
· 
/skill.md

Which endpoint do I need?

如何选择端点？

I want to...Call
Search posts by keyword or operator (
from:
, 
since:
, 
min_faves:
, ...)
GET /api/search
Search accounts by name
GET /api/search/users
Look up a profile by @handle
GET /api/handle/{handle}
Get a user's followers or followings
GET /api/user/{id}/followers
or 
/followings
Get a single post by ID
GET /api/tweet/{id}
See who reposted a post
GET /api/tweet/{id}/retweeters
Read an X List's posts or members
GET /api/list/{id}/tweets
or 
/members
Check trending topics for a country
GET /api/trends
Full param details for every row: 
references/endpoints.md
.
我想...调用
按关键词或运算符（
from:
、
since:
、
min_faves:
等）搜索帖子
GET /api/search
按名称搜索账号
GET /api/search/users
通过@用户名查找个人资料
GET /api/handle/{handle}
获取用户的关注者或关注对象
GET /api/user/{id}/followers
或 
/followings
通过ID获取单条帖子
GET /api/tweet/{id}
查看谁转发了某条帖子
GET /api/tweet/{id}/retweeters
查看X列表的帖子或成员
GET /api/list/{id}/tweets
或 
/members
查询某国的热门话题
GET /api/trends
每一行的完整参数详情：
references/endpoints.md
。

Authentication

认证方式

Two ways to pay, same data — full mechanics in the 
fetcher
skill:
bash
undefined
两种付费方式，获取的数据相同——完整机制见
fetcher
skill：
bash
undefined

1. Prepaid credits (recommended — get a key at https://fetcher.sh/topup

1. 预付费（推荐——在https://fetcher.sh/topup获取密钥

or via POST /api/credits/topup, see the fetcher skill)

或通过POST /api/credits/topup，详见fetcher skill）

export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx" curl -H "Authorization: Bearer $FETCHER_API_KEY"
"https://twitter.fetcher.sh/api/search?query=hello"
export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx" curl -H "Authorization: Bearer $FETCHER_API_KEY"
"https://twitter.fetcher.sh/api/search?query=hello"

2. x402 pay-per-call — omit the header; a GET with no payment returns 402

2. x402按调用付费——省略请求头；无付费信息的GET请求会返回402状态码

with machine-readable payment requirements (USDC on Base, Polygon,

并附带机器可读的付费要求（在Base、Polygon、Arbitrum、Monad或Solana链上支付USDC）。@x402/fetch会自动签名并重试请求。

Arbitrum, Monad, or Solana). @x402/fetch signs and retries automatically.

—

Every response is `{ "status": number, "message": string, "data": ... }`; the
HTTP status mirrors `status`.

所有响应格式均为`{ "status": number, "message": string, "data": ... }`；HTTP状态码与`status`字段一致。

Endpoints (15 — all GET, $0.005/call unless noted)

端点（共15个——均为GET请求，除非特别说明，价格为$0.005/次调用）

EndpointPriceWhat it returns
/api/search
$0.005Posts matching a query; supports X's advanced search operators
/api/search/users
$0.005Accounts matching a name/keyword query
/api/handle/{handle}
$0.005Profile by @handle
/api/handle/{handle}/about
$0.005Extended profile/about info by @handle
/api/user/{id}
$0.005Profile by numeric user ID
/api/user/{id}/tweets
$0.005A user's post timeline
/api/user/{id}/replies
$0.005A user's replies
/api/user/{id}/followers
$0.005A user's followers
/api/user/{id}/followings
$0.005Accounts a user follows
/api/tweet/{id}
$0.002A single post by ID
/api/tweet/{id}/replies
$0.005Replies to a post
/api/tweet/{id}/retweeters
$0.005Accounts that reposted a post
/api/list/{id}/members
$0.005An X List's member accounts
/api/list/{id}/tweets
$0.005An X List's post feed
/api/trends
$0.005Trending topics for a country
{id}
/ 
{handle}
are path parameters — substitute the real value. Optional query params (
cursor
, 
sort
) paginate or reorder; only 
query
(search) and 
country
(trends) are required elsewhere they appear.
端点价格返回内容
/api/search
$0.005匹配查询条件的帖子；支持X的高级搜索运算符
/api/search/users
$0.005匹配名称/关键词查询的账号
/api/handle/{handle}
$0.005通过@用户名获取的个人资料
/api/handle/{handle}/about
$0.005通过@用户名获取的扩展个人资料/简介信息
/api/user/{id}
$0.005通过数字用户ID获取的个人资料
/api/user/{id}/tweets
$0.005用户的帖子时间线
/api/user/{id}/replies
$0.005用户的回复内容
/api/user/{id}/followers
$0.005用户的关注者
/api/user/{id}/followings
$0.005用户关注的账号
/api/tweet/{id}
$0.002通过ID获取的单条帖子
/api/tweet/{id}/replies
$0.005某条帖子的回复
/api/tweet/{id}/retweeters
$0.005转发某条帖子的账号
/api/list/{id}/members
$0.005X列表的成员账号
/api/list/{id}/tweets
$0.005X列表的帖子信息流
/api/trends
$0.005某国的热门话题
{id}
/ 
{handle}
为路径参数——替换为实际值。可选查询参数（
cursor
、
sort
）用于分页或重新排序；仅
query
（搜索）和
country
（热门话题）在出现时为必填参数。

Scenarios

使用场景

The query on 
/api/search
goes straight to X's own search, so its operators work as-is: 
from:
, 
to:
, 
since:
, 
until:
, 
min_faves:
, 
min_retweets:
, 
filter:
, 
-filter:
.
Everything from one account:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/search?query=from%3AOpenAI&sort=Latest"
Between two dates:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=x402 since:2026-01-01 until:2026-02-01" -G \
  "https://twitter.fetcher.sh/api/search"
Popular posts only, replies excluded:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=ai agents min_faves:500 -filter:replies" -G \
  --data-urlencode "sort=Top" \
  "https://twitter.fetcher.sh/api/search"
Search accounts by name:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=climate scientist" -G \
  "https://twitter.fetcher.sh/api/search/users"
Resolve a profile by handle, then pull its bio/about:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/handle/nasa"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/handle/nasa/about"
A user's posts, replies, followers, or followings (by numeric ID from the handle lookup above):
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/user/11348282/tweets"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/user/11348282/followers"
A single post, its replies, and who reposted it:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/tweet/1234567890123456789"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/tweet/1234567890123456789/replies"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/tweet/1234567890123456789/retweeters"
An X List's members and posts:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/list/1234567890/members"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/list/1234567890/tweets"
Trending topics for a country:
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/trends?country=United%20States"
/api/search
的查询会直接发送至X的搜索系统，因此其运算符可直接使用：
from:
、
to:
、
since:
、
until:
、
min_faves:
、
min_retweets:
、
filter:
、
-filter:
。
获取某一账号的所有内容：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/search?query=from%3AOpenAI&sort=Latest"
获取某一时间段内的内容：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=x402 since:2026-01-01 until:2026-02-01" -G \
  "https://twitter.fetcher.sh/api/search"
仅获取热门帖子，排除回复：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=ai agents min_faves:500 -filter:replies" -G \
  --data-urlencode "sort=Top" \
  "https://twitter.fetcher.sh/api/search"
按名称搜索账号：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=climate scientist" -G \
  "https://twitter.fetcher.sh/api/search/users"
通过用户名解析个人资料，然后获取其简介信息：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/handle/nasa"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/handle/nasa/about"
获取用户的帖子、回复、关注者或关注对象（使用上述用户名查询得到的数字ID）：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/user/11348282/tweets"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/user/11348282/followers"
获取单条帖子、其回复以及转发者：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/tweet/1234567890123456789"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/tweet/1234567890123456789/replies"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/tweet/1234567890123456789/retweeters"
获取X列表的成员和帖子：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/list/1234567890/members"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/list/1234567890/tweets"
获取某国的热门话题：
bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://twitter.fetcher.sh/api/trends?country=United%20States"

MCP

MCP

json
{
  "mcpServers": {
    "x": {
      "url": "https://twitter.fetcher.sh/mcp",
      "headers": { "Authorization": "Bearer bby_live_..." }
    }
  }
}
Free: 
search_endpoints
, 
describe_endpoint
, 
check_balance
. Paid: 
fetch_data
(any endpoint above), 
topup_credits
, plus the named shortcut 
twitter_search
. Drop the 
headers
block to pay per call with x402 instead — see the 
fetcher
skill for the full flow.
json
{
  "mcpServers": {
    "x": {
      "url": "https://twitter.fetcher.sh/mcp",
      "headers": { "Authorization": "Bearer bby_live_..." }
    }
  }
}
免费功能：
search_endpoints
、
describe_endpoint
、
check_balance
。付费功能：
fetch_data
（上述任意端点）、
topup_credits
，以及命名快捷方式
twitter_search
。如果要改用x402按调用付费，可移除
headers
块——完整流程见
fetcher
skill。

Errors

错误说明

  • 400
    — missing/invalid parameter (message names it)
  • 401
    — unknown or rotated key
  • 402
    — payment required (x402 challenge) or 
    topup_required
    (credits exhausted)
  • 404
    — not a priced path
  • No rate limits; no refunds on upstream failures (settlement precedes delivery)
  • 400
    —— 参数缺失/无效（消息中会指明具体参数）
  • 401
    —— 密钥未知或已过期
  • 402
    —— 需要付费（x402验证）或
    topup_required
    （预付费余额耗尽）
  • 404
    —— 路径未定价
  • 无速率限制；上游失败不退款（结算先于数据交付）

Reference

参考资料