オブジェクト

上で参照した形式を、フィールドごとに説明します。型は略式です: 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` では投稿者の ID)
`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	`kind` が確定していれば `true`。`false` になるのは `kind` が `tweet` の薄い最初のフレームだけで、その投稿はまだ引用である可能性があります。同じ `id` で続く `update` が確定させます
`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 (メディア)

1 枚の画像、動画、または 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 が含まれ、同じ id の update が全文を届けるまで text は null です。

フィールド	型	意味
`id`	string	記事の ID
`title`	string	タイトル
`preview`	string	記事の冒頭部分
`text`	string \| null	全文（段落は空行で区切られます）。最初のフレームでは `null`
`cover`	string \| null	カバー画像の URL
`images`	string[]	記事内の画像
`url`	string	X 上の記事へのリンク

Delete ペイロード

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 ペイロード

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 ペイロード

search.match の d: Tweet ペイロードに、マッチに関する 3 つのフィールドを加えたもの。エンベロープの target は投稿者で、監視対象である必要はありません。

フィールド	型	意味
`keyword.id`	int	マッチしたキーワードの ID
`keyword.query`	string	そのクエリ
`keyword.label`	string \| null	そのラベル (設定している場合)
`author`	User	投稿者の完全なプロフィール
`author_is_target`	bool	投稿者がこのシステム上で監視されているアカウントでもある場合に `true`
`…`	TweetPayload	Tweet ペイロードのすべてのフィールド

Target (監視対象)

このキーから見た、監視中のアカウント 1 件。

フィールド	型	意味
`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`

Pending target (解決待ちの監視対象)

要求したアカウントの解決中に 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`

Keyword (キーワード)

X 検索で監視するクエリ 1 件。

フィールド	型	意味
`id`	int	数値 ID。削除時に使います
`query`	string	X 検索構文のクエリ
`label`	string \| null	お客様のラベル。すべてのマッチで返されます
`active`	bool	オペレーターが一時停止した場合は `false`
`hits`	int	これまでに配信したマッチ数
`last_hit_at`	datetime \| null	最後のマッチ
`last_run_at`	datetime \| null	最後の検索

Account (アカウント)

使用したキーについて GET /v1/account が返すもの。

フィールド	型	意味
`name`	string	発行時に付けられたキーの名前
`plan`	string	プランのプリセット
`key_id`	string	キーの短い ID。サポートへの問い合わせで引用しても安全です
`scopes`	string[]	キーが持つスコープ
`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 に送った項目ごとに 1 エントリ、同じ順序で。

フィールド	型	意味
`index`	int	リクエスト内での項目の位置
`status`	int	単体エンドポイントなら返していた HTTP ステータス
`data`	object (on success)	成功時: 単体エンドポイントのレスポンスボディ
`error`	{code, message, details?} (on failure)	失敗時: 通常のエラーオブジェクト

Profile (読み取り)

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`)

User 参照

フォローリストの読み取りで使うコンパクトな形式。

フィールド	型	意味
`id`	string	数値 ID
`screen_name`	string	ハンドル
`name`	string	表示名