UnifAPI 免费 X 端点针对帖子、资料、分页、速率限制和错误返回的每个字段，附类型说明与需要处理的边界情况。

一句话总结：UnifAPI 的 X 端点免费、无需登录、按访客限流，返回三种记录（post、profile，以及包着列表的 page），外加一种错误形状和三个限流响应头。字段名是 camelCase，id 是字符串（它们超过 2^53），日期是 UTC 的 ISO 8601，计数是整数，X 没有报告的任何东西都是缺失而不是零。本页列出每个字段的类型，以及程序必须处理的情况：转发会携带原帖加 repostedBy，引用只嵌套一层，受保护账号返回计数但不返回帖子，views 在多数帖子上有、但并非全部。

模型擅长读它见过的 JSON。一个正确使用数据源的智能体和一个瞎猜字段名的智能体，差别在于这份参考是在它的上下文里还是只在训练数据里。这就是那份参考。它与给人看的查看器页面渲染的是同一个模型，所以你在 /tools/x-profile-viewer 上看到的，正是 /tools/x/profile?handle=… 返回的。

约定

id 是字符串。 X 的 id 是 64 位；JSON 数字在 2^53 以上会丢失精度。每个 id 都是字符串，URL 和 cursor 里也一样。
日期是 ISO 8601，UTC。 createdAt 和 joinedAt 形如 2026-10-05T22:33:56.000Z。
计数是整数。 绝不是格式化字符串，绝不是 null。X 没有报告的计数会被省略，而不是设为 0。
可选即缺失。 标为可选的字段在没有值时不会出现在对象里。用 "views" in post.metrics 来判断，而不是 === 0。
URL 是规范的 x.com URL。 post.url 是 https://x.com/<handle>/status/<id>；媒体 URL 指向 X 的 CDN，从不二次托管。

`post`

由 /tools/x/post 返回（作为 post），也作为 profile、media 和 search 上 posts.items 的每一项，以及 replies 上 replies.items 的每一项。

字段	类型	含义
`id`	string	帖子 ID
`text`	string	完整正文。长帖（notes）完整返回；附有媒体时，末尾的媒体短链会被移除
`createdAt`	string（ISO 8601）	发布时间
`language`	string，可选	X 检测到的 BCP-47 代码（`en`、`ja`……）
`conversationId`	string，可选	该帖子所属线程的根帖子 id
`inReplyToPostId`	string，可选	当它是回复时，所回复的帖子
`possiblySensitive`	boolean	X 自己的标记
`url`	string	规范的 x.com URL
`author`	`profile` 或 `null`	作者；仅当 X 隐去时为 `null`
`metrics`	object	见下
`media`	`media` 数组	没有时为空
`repostedBy`	object 或 `null`	当这条记录是转发时设置：转发账号的 `{ id, handle, name }`。记录的其余部分是原帖
`quoted`	`post` 或 `null`	当这是引用帖时，被引用的帖子，嵌套一层（引用里的引用不会展开）

`metrics`

字段	类型	含义
`likes`	integer
`reposts`	integer	转发（retweet），不含引用
`replies`	integer	X 的回复计数；可能高于可读的公开回复数
`quotes`	integer	引用帖
`bookmarks`	integer
`views`	integer，可选	展示次数。X 在多数帖子上报告；未报告时缺失

`media`

字段	类型	含义
`kind`	`photo` \| `video` \| `animated_gif`
`url`	string，可选	全尺寸图片，或视频和 GIF 的封面帧
`previewUrl`	string，可选	目前与 `url` 相同；为较小尺寸版本预留
`width`、`height`	integer，可选	原始尺寸
`durationMs`	integer，可选	视频时长
`videoUrl`	string，可选	X 提供的最高码率 MP4，位于 X 的 CDN

`profile`

由 /tools/x/profile、/tools/x/media 和 /tools/x/followers 返回（作为 profile），也作为 post.author，以及 followers 上 users.items 的每一项。

字段	类型	含义
`id`	string	用户 ID
`handle`	string	不带 `@`，按 X 的大小写（`NASA`）
`name`	string	显示名
`verified`	boolean	任何形式的认证（蓝标、政府、企业）
`verifiedType`	string，可选	`Government`、`Business`……当 X 标明时
`protected`	boolean	帖子不公开。端点返回计数但不返回帖子
`bio`	string	可能为空
`location`	string	自由文本，可能为空
`website`	string，可选	展开后的 URL，不是 t.co 短链
`joinedAt`	string（ISO 8601）
`avatarUrl`	string，可选	400×400 尺寸版本
`bannerUrl`	string，可选
`followers`	integer
`following`	integer
`posts`	integer	历史累计帖子数
`listed`	integer，可选	该账号被加入的列表数，当有报告时
`pinnedPostId`	string，可选
`url`	string	`https://x.com/<handle>`

/tools/x/profile 另加 engagementRate：当前页上每条原创帖子的点赞、回复、转发和引用的平均值，除以关注者数，以百分比表示，保留四位有效数字。转发不计入平均。对于一个有 9000 万关注者的账号，这是一个很小的数（0.0058），这是正确的，不是 bug。

`page`

每个列表都被包装：

{ "items": [ … ], "hasMore": true, "nextCursor": "DAAHCgABHUAq3YL__-wLAAIAAAATMj…" }

字段	类型	含义
`items`	array	`post` 记录，或 `followers` 上的 `profile` 记录，或 `community` 记录
`hasMore`	boolean	当且仅当 `nextCursor` 有值时为 true
`nextCursor`	string 或 `null`	不透明。作为 `cursor=` 传回以获取下一页

页大小：profile 10 条帖子，media 12 条，replies、search 和 communities 20 条，followers 50 条，热搜 30 条。cursor 不透明；有的像 20@，有的像 X 自己的 DAAH… 字符串。永远不要解析它们。

热搜和社区

/tools/x/trends 返回 { woeid, locationSlug, generatedAt, trends: [ { rank, name, postCount?, url } ] }。postCount 只在 X 报告了帖子量的热搜上出现；对今天的大多数地区来说一个都没有，所以把它当作可选。url 是 x.com 上的实时搜索。

/tools/x/communities 返回 { query, communities: page }，其中每一项是 { id, name, description, memberCount?, access?, joinPolicy?, createdAt?, url }。

限流响应头

每个响应都带，无论成功还是出错：

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset: 1791357984

Reset 是当前 10 分钟窗口结束时的 Unix 秒数。一次搜索计 2 个单位，其余都是 1 个。429 另加以秒为单位的 Retry-After。

错误

每个非 2xx 响应都是：

{ "error": { "type": "not_found", "message": "X user not found: @nobody_here_123" } }

`type`	HTTP	何时
`validation_error`	400	输入缺失或格式错误（`Missing handle: pass ?handle=…`）
`not_found`	404	没有这个账号或帖子；被封禁的账号会在消息里说明
`rate_limited`	429	达到免费限额；响应体另加 `retryAfterSeconds` 和 `upgrade`
`upstream_error`	502	X 的数据层返回了错误
`upstream_unavailable`	503	超时或无法访问
`not_configured`	503	该部署没有配置上游凭据

按 type 分支；message 是给人看的，可能会变。

Markdown 模式

给任意端点加上 format=md 或发送 Accept: text/markdown，同一条记录就会渲染成 Markdown：一个带作者的标题、正文、一行指标、媒体链接、URL，以及写明下一个 cursor 的页脚。它包含上面的每个字段，除了作者对象里的原始 id，而且是把一个主页或一条线程放进模型上下文最省的方式。

样例在哪里

每个工具的 Markdown 页面都带有该端点抓取的真实响应，裁剪到几条：/tools/x-profile-viewer/index.md、/tools/x-post-viewer/index.md、/tools/x-search/index.md 等等。/llms.txt 列出全部八个，各附一个示例 URL。计量 X / Twitter API 在工作区密钥之后使用相同的字段名，所以针对免费端点写的代码不用改就能迁移。