X 数据 API
X 主页、帖子、回复、关注图谱与趋势，通过一个 REST 接口返回规范化 JSON。
- 10 个能力族
- 10 个文档化端点
按能力族分组的端点汇总
账号身份：主页查询，返回含简介、认证与粉丝字段的规范化 JSON。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username} | x.profile |
发布与动态流：账号、话题标签或音乐页发布过的内容，按序返回。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/posts | x.user_posts |
单内容查询：一条内容及其附属数据——评论、点赞者、媒体——全部规范化返回。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/posts/{id}/comments | x.comments |
搜索与趋势：内容与账号的关键词搜索、热搜榜与趋势话题。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/search/posts | x.search_posts |
关系图谱：关注者与关注列表，以分页的规范化 JSON 返回。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/followers | x.user_followers |
关系图谱：关注者与关注列表，以分页的规范化 JSON 返回。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/following | x.user_following |
发布与动态流：账号、话题标签或音乐页发布过的内容，按序返回。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/replies | x.user_replies |
单内容查询：一条内容及其附属数据——评论、点赞者、媒体——全部规范化返回。
| 方法 | 路径 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/media | x.user_media |
常见问题
关于X数据 API
什么是X数据 API？
X数据 API 是 FetchPI 面向X的读取接口：一组有文档的 REST 端点，把公开可得的X数据以结构化 JSON 返回。你不需要解析页面，也不需要维护专门的爬虫——调用一个端点，读取字段名稳定的规范化响应，其 schema 形态与所有 FetchPI 平台一致。全部 10 个文档化端点按能力族组织，每个能力族都有独立的参考页、参数表和示例。
X数据 API 能取到哪些数据？
API 覆盖上表列出的X能力族：共 10 个能力族、10 个端点，每个都有参数与响应 schema 文档。典型场景包括主页数据补充、帖子与评论采集、粉丝图谱分析、关键词监控和趋势跟踪。每个能力族返回的具体字段见其能力页——契约之外的数据类型，API 一概不承诺。
X当前已发布的能力族：
- profile
- user_posts
- post
- comments
- search_posts
- user_followers
- user_following
- user_replies
- user_media
- trends
如何使用X数据 API
从零到第一次拿到响应，只需三步：
第 1 步——注册免费账号
在控制台注册。系统会自动创建工作区，注册赠送的积分可用于最初几次调用。
第 2 步——获取 API 密钥
在控制台创建密钥，之后每个请求都通过标准的 Authorization: Bearer 头携带它。
第 3 步——调用端点
从一个有文档的端点开始，例如 GET /v1/x/users/{username}，然后从响应中读取规范化 JSON。下面的示例可直接复制，使用契约自带的演示值：
curl -H "Authorization: Bearer $FETCHPI_API_KEY" \
"https://fetchpi.com/v1/x/users/newdev"数据新鲜度如何运作
每个端点都接受整个数据 API 统一的 freshness 参数：cache 直接回答存储快照、不触达上游；live 拉取更新的数据，可能产生额外积分费用；max_age 以秒为单位限定可接受的数据年龄。响应 meta 块会报告生成每个答案的模式、数据年龄与服务层，让下游系统基于事实处理新鲜度，而不是靠猜。API 不承诺上游的实时状态——meta 块就是你实际拿到什么如实报告。
X数据 API 与自建爬虫的对比
自建X爬虫意味着顺利路径归你，其余一切也归你：页面结构会变、反爬措施会收紧，每个解析修复都要排进你的排期。数据 API 把这些维护工作变成一纸契约——有文档的请求与响应 schema、为查无数据和限流场景发布的错误码，以及所有 FetchPI 平台共用的同一套集成形态。边界对双方都保持诚实：API 只提供公开可得的数据，从不要求你的账号凭据，它也不是X官方产品。
为什么团队用 FetchPI 获取X数据
三个理由，都体现在集成过程里，而不只是宣传里：
- 统一的规范化 schema——X响应与所有 FetchPI 平台使用同一套字段结构，多平台管线只需解析一次。
- 新鲜度透明——每个响应都报告自己的新鲜度模式、数据年龄与服务层；每次请求你自行选择 cache 或 live，并按此付费。
- 按量计费——按次计积分，每个能力价格公开，没有席位费也没有固定套餐；meta 块报告每次调用的实际消耗。
费用与限制
按次以积分计费：每个能力都有公开的单次调用价格，缓存命中比实时拉取便宜，充值自助完成。端点有速率限制——触发限流的调用会返回文档中定义的 RATE_LIMIT_EXCEEDED 错误，而不是静默失败——每个响应的 meta 块也会报告本次消耗的积分。各能力的当前价格见定价页；错误码与限流的完整参考见文档。