对象

上文引用的各种结构，逐字段说明。类型是非正式的：string[] 表示字符串数组，A | null 表示可能缺失。

信封

出现在每个事件上：流中、GET /v1/events 中以及 Webhook 投递中。

字段	类型	含义
`v`	int	信封版本。目前为 `1`
`t`	string	事件类型，见下表
`op`	create \| update \| delete	`create`、`update`（同一 id 的补全）或 `delete`
`id`	string	稳定标识。按它去重
`ts`	int (ms)	在 X 上发生的时间，自纪元起的毫秒数。X 不提供资料变更、关注与取关、新增认证粉丝和删帖发生的时刻：这些事件的值是我们检测到的时间
`sid`	string	用于回放的流位置；出现在流中和历史记录中
`target.id`	string	被监控账号的 X 数字 id（`search.match` 中为帖子作者的）
`target.screen_name`	string	被监控账号的用户名
`target.name`	string	账号的显示名
`d`	object	类型专属载荷

Tweet 载荷

tweet.create、tweet.reply、tweet.retweet 和 tweet.quote 的 d，也是 search.match 的基础。

字段	类型	含义
`tweet_id`	string	帖子 id，字符串
`kind`	tweet \| reply \| retweet \| quote	帖子的种类
`text`	string	全文（含长帖）
`lang`	string \| null	X 检测到的语言
`author`	User	发布它的账号，完整的 User 对象，与 `search.match` 的作者相同：用户名、显示名、简介、头像、横幅、各项计数、认证、位置、链接和注册时间。精简第一帧里是最近一次读到的账号资料；`update` 携带与帖子一同读到的资料
`reply_to`	Brief+ \| null	回复时：被回复的帖子——一个 Brief 加上其作者的 `screen_name`、`tweet_id` 和 `user_id`
`retweet_of`	Brief \| null	转推时：原帖
`quoted`	Brief \| null	引用时：被引用的帖子
`media`	string[]	纯图片 URL，每个媒体项一个
`media_items`	Media[]	每个媒体项，含类型、视频变体和尺寸
`urls`	string[]	帖子中展开后的链接
`article`	Article \| null	帖子链接了 X 文章时：该文章
`counts`	{reply, rt, like, quote, bookmark}	我们读取时的回复、转推、点赞、引用和书签计数
`views`	int \| null	浏览量，X 提供时才有
`url`	string	帖子的规范链接
`full`	bool	在第一帧精简的 `create` 上为 `false`；事件携带整条帖子后为 `true`
`kind_final`	bool	`true` 表示 `kind` 已确定；`false` 只出现在 `kind` 为 `tweet` 的精简第一帧上：这条帖子仍可能是引用，随后的 `update`（同一 `id`）会给出定论
`kind_was`	tweet \| null (update only)	只出现在确定帖子种类的那个 `update` 上，且仅当第一帧给出的种类不同：第一帧当时的种类（结果是引用的帖子为 `tweet`）
`edit_of`	Brief \| null	仅 `tweet.edit`：被这一版替换的版本（它的 id，以及我们有记录时的正文和作者）

Brief（简要帖子）

嵌入在其他事件中的紧凑帖子：转推的原帖、被引用的帖子、被回复的帖子或置顶帖子。

字段	类型	含义
`id`	string	帖子 id
`user`	string	作者的用户名
`name`	string	作者的显示名称
`user_id`	string	作者的数字 id
`text`	string	全文
`media`	string[]	纯图片 URL
`media_items`	Media[]	媒体项，含类型和视频变体
`created_ms`	int	发布时间，自纪元起的毫秒数
`url`	string	帖子链接

Media（媒体）

一张图片、一段视频或一个 GIF。视频携带我们能找到的最高码率 MP4；url 是封面帧。

字段	类型	含义
`type`	photo \| video \| animated_gif	媒体种类
`url`	string	图片 URL，或视频的封面帧
`expanded_url`	string	该帖子在 X 上的媒体页
`video_url`	string (video)	MP4 URL，可用的最高码率
`bitrate`	int (video)	该 MP4 的码率
`duration_ms`	int (video)	视频时长
`width`	int	原始宽度，像素
`height`	int	原始高度，像素

Article（文章）

帖子所链接的 X 文章（长文）。第一帧携带 title 和 preview；text 为 null，直到同一 id 随后的 update 带来全文。

字段	类型	含义
`id`	string	文章 id
`title`	string	标题
`preview`	string	文章开头的几行
`text`	string \| null	全文，段落之间以空行分隔；第一帧中为 `null`
`cover`	string \| null	封面图片 URL
`images`	string[]	文章中的图片
`url`	string	文章在 X 上的链接

删除载荷

tweet.delete 的 d。只针对我们见过且现已消失的帖子发送。它的 ts 是我们检测到删除的时间；帖子本身的时间在它之前的 create 帧里。

字段	类型	含义
`tweet_id`	string	被删帖子的 id
`url`	string	它原来的位置

资料变更载荷

所有 profile.* 事件的 d。这些事件的 op 为 update。

字段	类型	含义
`field`	string	哪个资料字段变了；与类型中 `profile.` 之后的词相同
`old`	any	之前的值
`new`	any	新的值
`tweet`	Brief (pinned only)	`profile.pinned` 时：新置顶的帖子
`old_tweet`	Brief (pinned only)	`profile.pinned` 时：之前置顶的帖子，如果我们有的话

关注载荷

follow.add、follow.remove 和 followers.verified.add 的 d。

字段	类型	含义
`user`	User	对方账号，完整的 User 对象

账号状态载荷

account.status 的 d。状态取值为 active（正常）、protected（帖子仅对批准的关注者可见）、suspended（被 X 封禁）或 unavailable（已停用、已删除或因其他原因不可见）。ts 是我们检测到变化的时间。

字段	类型	含义
`old`	active \| protected \| suspended \| unavailable	之前的状态
`new`	active \| protected \| suspended \| unavailable	现在的状态
`reason`	string \| null	X 给出的原文说明（如有，例如 `Suspended`）

User（用户）

完整的账号资料，嵌入在关注事件和 search.match 中。

字段	类型	含义
`id`	string	数字 id
`screen_name`	string	用户名
`name`	string	显示名称
`bio`	string	简介文本
`avatar`	string	头像图片 URL
`banner`	string \| null	横幅图片 URL
`followers`	int	粉丝数
`following`	int	关注数
`tweets`	int	帖子数
`location`	string	自由文本的位置
`url`	string \| null	展开后的资料链接
`verified`	bool	是否有认证标识
`verified_type`	string \| null	`blue`、`business`、`government` 或 `null`
`protected`	bool	帖子仅对已批准的粉丝可见
`created_at`	string (ISO-8601)	账号创建时间
`category`	string \| null	职业类别，如果账号设置了的话

搜索命中载荷

search.match 的 d：一个 Tweet 载荷加上关于命中的三个字段。信封中的 target 是帖子作者，不必是你的监控目标之一。

字段	类型	含义
`keyword.id`	int	命中的关键词的 id
`keyword.query`	string	它的查询
`keyword.label`	string \| null	它的标签，如果你设置了的话
`author`	User	作者的完整资料
`author_is_target`	bool	如果作者同时也是本系统监控的账号，则为 `true`
`…`	TweetPayload	Tweet 载荷的所有字段

监控目标

你监控的一个账号，从此密钥的视角看。

字段	类型	含义
`id`	string	X 数字 id。它永远不变：请以它作为记录的主键
`screen_name`	string	当前用户名。它可能改变，`profile.screen_name` 会告诉你
`name`	string	显示名称
`previous_screen_names`	string[]	账号以前用过的用户名，最近的在前。每一个都仍可用于 `/v1/monitor/targets/{target}`
`push_ready`	bool	你为这个账号订阅的所有事件类型都已在实时采集。为 `false` 时也不会扣留任何内容：账号从订阅那一刻起就受到监控，事件一经采集即送达，所以处理事件前无需等待这个标志
`last_push_at`	datetime \| null	上次收到它的实时事件的时间
`last_poll_at`	datetime \| null	上次读取其时间线的时间
`state`	"subscribed"	此处始终为 `subscribed`；待解析的有自己的结构
`event_types`	string[]	为该账号送达的事件类型；为空表示密钥允许的全部类型
`event_types_all`	bool	`event_types` 为空时为 `true`

待解析目标

你请求的账号仍在解析时，GET /v1/monitor/targets/{target} 返回的内容。

字段	类型	含义
`screen_name`	string \| null	你请求的用户名（按用户名请求时）
`user_id`	string \| null	你请求的用户 id（按 id 请求时）
`state`	"queued"	始终为 `queued`
`queued_at`	int (unix s)	你请求的时间
`event_types`	string[]	为它选定的事件类型，解析完成后生效
`event_types_all`	bool	`event_types` 为空时为 `true`

关键词

你在 X 搜索中监视的一个查询。

字段	类型	含义
`id`	int	数字 id；删除时用它
`query`	string	查询，X 搜索语法
`label`	string \| null	你的标签，在每次命中中回显
`active`	bool	运营方暂停了它则为 `false`
`hits`	int	至今投递的命中数
`last_hit_at`	datetime \| null	上次命中
`last_run_at`	datetime \| null	上次搜索

账户

GET /v1/account 返回的关于你所用密钥的信息。

字段	类型	含义
`name`	string	密钥名称，发放时所定
`plan`	string	套餐预设
`key_id`	string	密钥的短 id，可安全地在支持请求中引用
`scopes`	string[]	密钥持有的 scope
`event_types`	string[]	密钥级事件类型白名单，由我们管理；空表示全部
`event_types_all`	bool	过滤器为空时为 `true`
`limits.max_targets`	int	被监控账号上限
`limits.max_conns`	int	并发 WebSocket 上限
`limits.max_keywords`	int	关键词上限
`limits.requests_per_minute`	int	每分钟请求预算
`usage.targets`	int	当前监控的账号数
`usage.keywords`	int	当前监视的关键词数

Webhook

GET /v1/account/webhook 返回的内容。

字段	类型	含义
`url`	string \| null	已注册的端点
`stats`	{ok, http_`…}`	投递计数器：`ok`，以及每种见过的失败状态各一个 `http_<code>`

Meta（分页信息）

每个列表旁的分页信息。

字段	类型	含义
`count`	int	本页条目数
`has_more`	bool	是否还有下一页
`next_cursor`	string \| null	作为 `?cursor=` 回传；到底时为 `null`

批量结果

发送到 POST /v1/monitor/targets:batch 的每一项对应一个条目，顺序相同。

字段	类型	含义
`index`	int	该项在你请求中的位置
`status`	int	单项端点本会返回的 HTTP 状态
`data`	object (on success)	成功时，单项响应体
`error`	{code, message, details?} (on failure)	失败时，常规错误对象

资料（读取）

GET /v1/users/{screen_name}、/v1/users/by-id/{user_id} 和 /v1/users/batch 对每个账号返回的内容。

字段	类型	含义
`id`	string	数字 id
`name`	string	显示名称
`screen_name`	string	用户名
`bio`	string	简介文本
`location`	string	自由文本的位置
`url`	string \| null	资料链接
`avatar`	string	头像图片 URL
`banner`	string \| null	横幅图片 URL
`pinned`	string \| null	置顶帖子的 id
`verified`	bool	是否有认证标识
`protected`	bool	帖子仅对已批准的粉丝可见
`followers`	int	粉丝数
`following`	int	关注数
`tweets`	int	帖子数

Tweet（读取）

读取端点返回的帖子。信息与 Tweet 载荷相同，但采用我们解析器输出的更扁平的结构。

字段	类型	含义
`id`	int	帖子 id，数字
`created_ms`	int	发布时间，自纪元起的毫秒数
`user_id`	int	作者的数字 id
`user`	string	作者的用户名
`name`	string	作者的显示名称
`text`	string	全文
`lang`	string \| null	X 检测到的语言
`reply_to`	string \| null	被回复者的用户名
`reply_to_status_id`	string \| null	被回复帖子的 id
`reply_to_user_id`	string \| null	被回复账号的 id
`conversation_id`	string	串帖根帖子的 id
`is_rt`	bool	是转推
`rt_of`	Brief \| null	转推时的原帖
`is_quote`	bool	引用了另一条帖子
`quoted`	Brief \| null	被引用的帖子
`media`	string[]	纯图片 URL
`media_items`	Media[]	媒体项，含类型和视频变体
`urls`	string[]	展开后的链接
`views`	int \| null	浏览量
`counts`	{reply, rt, like, quote, bookmark}	回复、转推、点赞、引用和书签计数
`article`	Article \| null	帖子链接到的 X 文章（如有）：标题、摘要、封面、图片；全文见 `GET /v1/tweets/{tweet_id}/article`
`edit_of`	int \| null	如果这是编辑后的版本：第一版的 id，否则为 `null`
`edit_ids`	int[]	所有版本的 id，最早的在前；从未编辑过的帖子只有它自己
`source`	string \| null	发帖所用的客户端，原样取自 X（一个 HTML 链接，例如 `Twitter for iPhone`）

用户引用

关注列表读取中使用的紧凑形式。

字段	类型	含义
`id`	string	数字 id
`screen_name`	string	用户名
`name`	string	显示名称