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
Endpoints	15, 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"

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/次调用）

Endpoint	Price	What it returns
`/api/search`	$0.005	Posts matching a query; supports X's advanced search operators
`/api/search/users`	$0.005	Accounts matching a name/keyword query
`/api/handle/{handle}`	$0.005	Profile by @handle
`/api/handle/{handle}/about`	$0.005	Extended profile/about info by @handle
`/api/user/{id}`	$0.005	Profile by numeric user ID
`/api/user/{id}/tweets`	$0.005	A user's post timeline
`/api/user/{id}/replies`	$0.005	A user's replies
`/api/user/{id}/followers`	$0.005	A user's followers
`/api/user/{id}/followings`	$0.005	Accounts a user follows
`/api/tweet/{id}`	$0.002	A single post by ID
`/api/tweet/{id}/replies`	$0.005	Replies to a post
`/api/tweet/{id}/retweeters`	$0.005	Accounts that reposted a post
`/api/list/{id}/members`	$0.005	An X List's member accounts
`/api/list/{id}/tweets`	$0.005	An X List's post feed
`/api/trends`	$0.005	Trending 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.005	X列表的成员账号
`/api/list/{id}/tweets`	$0.005	X列表的帖子信息流
`/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

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

参考资料

Deep dives:
```
references/endpoints.md
```
(every param) ·
```
references/scenarios.md
```
(one
```
curl
```
per endpoint) ·
```
references/faq.md
```
·
```
references/comparison.md
```
(vs. the official X API and a browser scraper)
Task guides: search tweets · export followers
Slash command:
```
/x-search
```
Full agent setup: https://twitter.fetcher.sh/skill.md
OpenAPI 3.1 contract: https://twitter.fetcher.sh/openapi.json
Condensed catalog: https://twitter.fetcher.sh/llms.txt
Payment, credits, and MCP deep dive:
```
fetcher
```
skill
Site: https://twitter.fetcher.sh

深度解析：
```
references/endpoints.md
```
（所有参数）·
```
references/scenarios.md
```
（每个端点对应一个
```
curl
```
示例）·
```
references/faq.md
```
·
```
references/comparison.md
```
（与官方X API和浏览器爬虫的对比）
任务指南：搜索推文 · 导出关注者
斜杠命令：
```
/x-search
```
完整Agent设置：https://twitter.fetcher.sh/skill.md
OpenAPI 3.1契约：https://twitter.fetcher.sh/openapi.json
精简目录：https://twitter.fetcher.sh/llms.txt
支付、预付费及MCP深度解析：
```
fetcher
```
skill
官网：https://twitter.fetcher.sh