XCRAP.CC
ZH

API 参考

每个接口都是 GET，不需要任何认证，你要五种格式里的哪一种它就回哪一种。基础 URL 在下面。除此之外没别的要配置。

基础 URL

https://xcrap.cc/v1

无需认证

没有密钥，没有 token，也没有要发的请求头。速率限制按 IP 和接口分别计算。

OpenAPI

完整规范以 JSON 和 YAML 提供。把任意生成器或者智能体框架指过去就行。

openapi.json openapi.yaml

响应格式

默认是 JSON。用 ?format= 或者 Accept 头覆盖。两者作用一致；同时出现时查询参数优先。

?format= Accept Content-Type
json application/json application/json
markdown text/markdown text/markdown
yaml application/yaml application/yaml
csv text/csv text/csv
html text/html text/html
x-markdown-tokens

每个 markdown 响应都带有读取成本估算，让智能体在拉取正文前就能判断一个串推是否放得进上下文。

速率限制

限制按接口分开算，而不是一个全局额度，因为一个批量请求可能要打五十次上游调用，而命中缓存的帖子一次都不用。每个响应都带 x-ratelimit-limit、x-ratelimit-remaining 和 x-ratelimit-reset。

额度 请求数 时间窗口 适用于
tweet 45 1 分钟 /v1/tweet
user 45 1 分钟 /v1/user
thread 15 1 分钟 /v1/thread
timeline 15 1 分钟 /v1/user/tweets
graph 15 1 分钟 /v1/user/followers, /v1/user/following
replies 15 1 分钟 /v1/replies
history 4 5 分钟 /v1/user/history
search 10 15 分钟 /v1/search
bulk 6 5 分钟 /v1/bulk
media 20 1 分钟 /v1/media, /v1/media/download
meta 90 1 分钟 /v1/trends
page 240 1 分钟 网站页面

还不够？企业版提供更高的限额和专属容量。 查看企业版 →

错误

错误会按你要求的格式返回，带一个稳定的、机器可读的 code，一条说明出了什么问题的 message，以及一条告诉你该怎么办的 hint。

状态码 code 怎么办
400 bad_request 缺少参数或参数格式错误。请对照本页检查。
404 not_found 帖子或账号已删除、被封禁、为私密或从未存在。
429 rate_limited 接口额度已用完。请等待 retry-after 给出的时间，或查看企业版以获得更高限额。
451 opted_out 该账号已要求从 XCrap 中排除。
500 internal_error 是我们的问题，已经上报。请稍后再试。
502 upstream_failed 所有来源都拒绝了。通常很快恢复，一分钟后重试。
504 upstream_timeout 某个来源没有及时响应。一分钟后重试。
503 search_unavailable 搜索额度暂时用完，或搜索尚未配置。请等待 retry-after 给出的时间。
试一下

填好参数直接发送。请求打到的是真实接口——没有密钥要填，所以这个表单和真实响应之间没有任何东西挡着。

GET /v1/tweet 45 / 1m

一条帖子，完整解析

获取单条帖子，包括作者、所有互动计数、各码率的附带媒体、投票结果，以及展开一层的被引用帖子。

/v1/tweet 端点的插图

参数

参数 类型 默认值 说明
url 必填 string 无 帖子 URL 或其数字 id。x.com、twitter.com、fx/vx 镜像以及单独的 id 都可以。
download boolean 无 发送 Content-Disposition，让浏览器把响应保存为文件。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/tweet?url=https://x.com/jack/status/20&format=markdown

试一下

download
format
fresh
GET /v1/tweet

这里的速率限制和别处完全一样。

GET /v1/thread 15 / 1m

完整的串推，按顺序展开

给它串推中的任意一条，包括第一条，它会按阅读顺序返回作者的帖子。X 只暴露帖子的父帖，所以 XCrap 按会话 id 拼接作者的时间线，向后走完整个串推。

/v1/thread 端点的插图

参数

参数 类型 默认值 说明
url 必填 string 无 串推中的任意一条帖子。
max_tweets integer 25 展开深度，1 到 100。响应会说明是否被截断。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/thread?url=https://x.com/naval/status/1002103360646823936&format=markdown

试一下

format
fresh
GET /v1/thread

这里的速率限制和别处完全一样。

GET /v1/replies 15 / 1m

帖子下的回复

帖子回复的一页，按点赞最多或最新排序，并附带帖子本身。只返回直接回复：回复的回复属于它自己的对话。不分页：这是 X 为该帖子提供的唯一一页，最多约一百条回复。

/v1/replies 端点的插图

参数

参数 类型 默认值 说明
url 必填 string 无 要读取回复的帖子：URL 或数字 id。
sort string top top 表示点赞最多的在前，recent 表示最新的在前。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/replies?url=https://x.com/naval/status/1002103360646823936&sort=top&format=markdown

试一下

sort
format
fresh
GET /v1/replies

这里的速率限制和别处完全一样。

GET /v1/search 10 / 15m

搜索帖子

对 X 进行全文搜索，支持 X 搜索能理解的运算符：from:、to:、"精确短语"、-排除、lang:、filter:links 等。可选择最新或最热门的帖子，或只要带图片或视频的帖子。每次调用返回一页；传入 next_cursor 获取下一页。搜索是所有端点中额度最紧的，结果缓存十分钟。

/v1/search 端点的插图

参数

参数 类型 默认值 说明
q 必填 string 无 要搜索的内容，可包含任意 X 搜索运算符。
feed string latest latest、top、photos 或 videos。
since string 无 要匹配的最早帖子，日期如 2025-01-01，或完整的 ISO 时间戳。
until string 无 要匹配的最新帖子，日期或完整的 ISO 时间戳。
cursor string 无 上一次响应中的 next_cursor。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/search?q=from:nasa%20mars&feed=latest&format=markdown
GET /v1/user 45 / 1m

个人资料

简介、所在地、网站、加入日期、认证类型、原始分辨率的头像和横幅，以及粉丝、关注、帖子和媒体数量。

/v1/user 端点的插图

参数

参数 类型 默认值 说明
handle 必填 string 无 用户名，带不带 @ 都可以，或完整的个人主页 URL。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/user?handle=naval&format=markdown

试一下

format
fresh
GET /v1/user

这里的速率限制和别处完全一样。

GET /v1/user/tweets 15 / 1m

账号的帖子

账号帖子的一页，从新到旧。分页用游标而不是偏移量，因为时间线在你阅读时会变化，偏移量会悄无声息地跳过或重复帖子。

/v1/user/tweets 端点的插图

参数

参数 类型 默认值 说明
handle 必填 string 无 要读取的账号。
count integer 20 返回的帖子数量，1 到 100。
cursor string 无 上一次响应中的 next_cursor。
exclude_replies boolean true 不包括该账号回复他人的帖子。
media_only boolean false 只包括带图片或视频的帖子。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/user/tweets?handle=naval&count=20

试一下

exclude_replies
media_only
format
fresh
GET /v1/user/tweets

这里的速率限制和别处完全一样。

GET /v1/user/followers 15 / 1m

谁关注了这个账号

关注该账号的账号的一页，每个都是完整的个人资料。页面大小由 X 决定，通常几十个；传入 next_cursor 获取下一页，最后一页时它为 null。

/v1/user/followers 端点的插图

参数

参数 类型 默认值 说明
handle 必填 string 无 要列出其粉丝的账号。
cursor string 无 上一次响应中的 next_cursor。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/user/followers?handle=jack&format=markdown

试一下

format
fresh
GET /v1/user/followers

这里的速率限制和别处完全一样。

GET /v1/user/following 15 / 1m

这个账号关注了谁

该账号关注的账号的一页，每个都是完整的个人资料。页面大小由 X 决定；传入 next_cursor 获取下一页，最后一页时它为 null。

/v1/user/following 端点的插图

参数

参数 类型 默认值 说明
handle 必填 string 无 要列出其关注对象的账号。
cursor string 无 上一次响应中的 next_cursor。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/user/following?handle=jack&format=markdown

试一下

format
fresh
GET /v1/user/following

这里的速率限制和别处完全一样。

GET /v1/user/history 4 / 5m

账号帖子，批量导出

遍历账号的时间线，一次响应最多返回 1,000 条帖子，从新到旧，可限定日期范围。遍历大约每二十条帖子耗时一秒，所以大批量导出时请使用 format=ndjson：帖子会在获取时逐行到达，大致从新到旧，而不是在最后一次性返回。日期范围越久远，X 自己的时间线就越残缺，几年前的范围可能只返回很少内容甚至为空。

/v1/user/history 端点的插图

参数

参数 类型 默认值 说明
handle 必填 string 无 要导出的账号。
max_posts integer 200 达到这么多帖子后停止，1 到 1000。
since string 无 要包含的最早帖子，日期如 2025-01-01，或完整的 ISO 时间戳。
until string 无 要包含的最新帖子，日期或完整的 ISO 时间戳。
include_replies boolean false 包括该账号回复他人的帖子。
include_reposts boolean false 包含该账号转发的其他账号的帖子。
format string json 响应格式：json、markdown、yaml、csv 或 html，或用 ndjson 逐行流式输出帖子。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/user/history?handle=naval&max_posts=200&since=2025-01-01

试一下

include_replies
include_reposts
format
fresh
GET /v1/user/history

这里的速率限制和别处完全一样。

GET /v1/trends 90 / 1m

当前热门

当前的热门话题，以及 X 为每个话题附上的上下文标签。缓存五分钟而不是五天，因为过期的热门列表还不如没有。

/v1/trends 端点的插图

参数

参数 类型 默认值 说明
count integer 20 话题数量，1 到 50。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/trends?count=10&format=markdown
GET /v1/media 20 / 1m

列出帖子的媒体

帖子附带的每个文件：类型、尺寸、时长、作者的替代文本、X 编码的每个视频版本，以及每个文件现成的下载链接。

/v1/media 端点的插图

参数

参数 类型 默认值 说明
url 必填 string 无 要查看的帖子。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

https://xcrap.cc/v1/media?url=https://x.com/i/status/1671370010743263233

试一下

format
fresh
GET /v1/media

这里的速率限制和别处完全一样。

GET /v1/media/download 20 / 1m

下载单个文件

带 Content-Disposition 头直接流式传输文件。不做缓冲，也不写入我们的磁盘，这正是隐私政策中数据保留承诺在实践中的含义。

/v1/media/download 端点的插图

参数

参数 类型 默认值 说明
url 必填 string 无 文件所属的帖子。
index integer 0 当帖子有多个文件时，选择哪一个。
quality string best best 或 worst。仅适用于视频；图片只有一种分辨率。

示例

https://xcrap.cc/v1/media/download?url=https://x.com/i/status/1671370010743263233&index=0

试一下

quality
GET /v1/media/download

这里的速率限制和别处完全一样。

POST /v1/bulk 6 / 5m

一次最多五十条帖子

一次请求解析多条帖子。失败按条计算：一个失效链接只会让该条返回错误，其他条目照常返回。也支持 GET，使用重复或逗号分隔的 url 参数。

/v1/bulk 端点的插图

参数

参数 类型 默认值 说明
urls 必填 string[] 无 一到五十个帖子 URL 或 id，放在 JSON 请求体中。
format string json 响应格式：json、markdown、yaml、csv 或 html。优先于 Accept 请求头。
fresh boolean false 跳过缓存，从上游重新获取。请谨慎使用。

示例

curl -X POST https://xcrap.cc/v1/bulk \
  -H 'content-type: application/json' \
  -d '{"urls":["https://x.com/jack/status/20","1671370010743263233"]}'

试一下

format
fresh
POST /v1/bulk

这里的速率限制和别处完全一样。