イベント

エンベロープ

すべてのイベントは同じエンベロープを持ち、d に以下で説明する種類ごとのペイロードが入ります。

フィールド	型	意味
`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.create`	投稿	アカウントが新しく投稿した
`tweet.reply`	投稿	誰かに返信した。`reply_to` に返信先の投稿がテキストとメディア付きで入ります
`tweet.retweet`	投稿	誰かの投稿をリポストした。`retweet_of` に元投稿の全体が入ります
`tweet.quote`	投稿	誰かの投稿を引用した。`quoted` に引用元投稿の全体が入ります
`tweet.edit`	投稿	投稿を編集しました。イベントは新しい版を運び、`edit_of` は置き換えられた版です
`tweet.delete`	投稿	アカウントが公開していた投稿が消えた
`profile.name`	プロフィール	表示名が変わった
`profile.screen_name`	プロフィール	ハンドルが変わった
`profile.bio`	プロフィール	自己紹介が変わった
`profile.location`	プロフィール	場所が変わった
`profile.url`	プロフィール	プロフィールリンクが変わった
`profile.avatar`	プロフィール	アバターが変わった。`old` と `new` は画像 URL
`profile.banner`	プロフィール	バナーが変わった。`old` と `new` は画像 URL
`profile.pinned`	プロフィール	固定投稿が変わった。`tweet` と `old_tweet` に投稿そのものが入ります
`profile.verified`	プロフィール	認証バッジが付いた、または外れた
`follow.add`	フォローグラフ	アカウントが誰かをフォローし始めた。`user` はその相手の完全なプロフィール
`follow.remove`	フォローグラフ	アカウントが誰かのフォローをやめた
`followers.verified.add`	フォローグラフ	認証済みアカウントがフォローし始めた。`user` に自己紹介、各種カウント、場所、登録日が入ります
`account.status`	アカウント	アカウントが非公開、凍結、閲覧不可になった、または通常に戻った
`search.match`	検索	誰かがキーワードのいずれかにマッチする投稿をした。`keyword` がどのキーワードかを示し、`author` は投稿者の完全なプロフィール

X は「フォローを開始した」「フォロワーを獲得した」のタイムスタンプを提供していません。そのためこれらのイベントでは、ts は当社が変更を検知した時刻です。

すべてのアカウントからすべての種類を受け取る必要はありません。イベント種類の選択で、一部だけ（例：新しい認証済みフォロワーだけ）を受け取る方法を説明しています。

ペイロード

5 種類のペイロード形式で 18 種類すべてのイベントをカバーします。

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 と、記録があれば本文と投稿者)

例

{
  "v": 1,
  "t": "tweet.create",
  "op": "create",
  "id": "tweet:2097879002992070835",
  "ts": 1789012345678,
  "sid": "1789012346012-0",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "tweet_id": "2097879002992070835",
    "kind": "tweet",
    "text": "Ash-covered shoes and a president in crisis…",
    "lang": "en",
    "author": {
      "id": "1652541",
      "screen_name": "Reuters",
      "name": "Reuters",
      "bio": "Top and breaking news, pictures and videos from Reuters.",
      "avatar": "https://pbs.twimg.com/profile_images/1874154135869616128/nJDmubGJ_normal.jpg",
      "banner": "https://pbs.twimg.com/profile_banners/1652541/1573687397",
      "followers": 25900000,
      "following": 1150,
      "tweets": 1080000,
      "location": "Around the world",
      "url": "https://www.reuters.com",
      "verified": true,
      "verified_type": "Business",
      "protected": false,
      "created_at": "2007-03-20T17:46:05Z",
      "category": null
    },
    "reply_to": null,
    "retweet_of": null,
    "quoted": null,
    "media": [
      "https://pbs.twimg.com/media/….jpg"
    ],
    "media_items": [
      {
        "type": "photo",
        "url": "https://pbs.twimg.com/media/….jpg",
        "expanded_url": "https://x.com/Reuters/status/2097879002992070835/photo/1",
        "width": 1200,
        "height": 675
      }
    ],
    "urls": [
      "https://reut.rs/…"
    ],
    "counts": {
      "reply": 12,
      "rt": 40,
      "like": 131,
      "quote": 3,
      "bookmark": 9
    },
    "views": 20411,
    "url": "https://x.com/Reuters/status/2097879002992070835",
    "full": true,
    "kind_final": true
  }
}

最初の create フレームは意図的に薄くしています。ID、投稿者（author。最後に読み取ったアカウント情報）、テキスト（短縮されることがあります）を持ち、投稿を検知した瞬間に送り出せるようにしています。url はすでに投稿を指しています。この時点では引用とオリジナル投稿を常に見分けられるとは限らないため、そのようなフレームは tweet.create で kind_final: false を持ちます。同じ id で続く update が上記の完全なペイロードと確定した種類を運びます。引用だった場合は tweet.quote と kind_was: "tweet" です。

同じ投稿を、補完前に最初に配信された時点の形

{
  "v": 1,
  "t": "tweet.create",
  "op": "create",
  "id": "tweet:2097879002992070835",
  "ts": 1789012345678,
  "sid": "1789012346012-0",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "tweet_id": "2097879002992070835",
    "kind": "tweet",
    "text": "Ash-covered shoes and a president in crisis…",
    "author": {
      "id": "1652541",
      "screen_name": "Reuters",
      "name": "Reuters",
      "bio": "Top and breaking news, pictures and videos from Reuters.",
      "avatar": "https://pbs.twimg.com/profile_images/1874154135869616128/nJDmubGJ_normal.jpg",
      "banner": "https://pbs.twimg.com/profile_banners/1652541/1573687397",
      "followers": 25900000,
      "following": 1150,
      "tweets": 1080000,
      "location": "Around the world",
      "url": "https://www.reuters.com",
      "verified": true,
      "verified_type": "Business",
      "protected": false,
      "created_at": "2007-03-20T17:46:05Z",
      "category": null
    },
    "url": "https://x.com/Reuters/status/2097879002992070835",
    "full": false,
    "kind_final": false
  }
}

Delete ペイロード

tweet.delete の d。当社が一度見た投稿が消えた場合にのみ送られます。ts は削除を検知した時刻で、投稿自体の時刻はそれ以前の create フレームにあります。

フィールド	型	意味
`tweet_id`	string	削除された投稿の ID
`url`	string	かつて投稿があった場所

例

{
  "v": 1,
  "t": "tweet.delete",
  "op": "delete",
  "id": "tweet:2097879002992070835:delete",
  "ts": 1789012345678,
  "sid": "…",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "tweet_id": "2097879002992070835",
    "url": "https://x.com/Reuters/status/2097879002992070835"
  }
}

プロフィール変更ペイロード

すべての profile.* イベントの d。これらでは op は update です。

フィールド	型	意味
`field`	string	変わったプロフィールのフィールド。種類名の `profile.` の後ろと同じ語
`old`	any	以前の値
`new`	any	新しい値
`tweet`	Brief (pinned only)	`profile.pinned` の場合: 新たに固定された投稿
`old_tweet`	Brief (pinned only)	`profile.pinned` の場合: 以前固定されていた投稿 (当社が持っていれば)

例

{
  "v": 1,
  "t": "profile.bio",
  "op": "update",
  "id": "profile:1652541:bio:9c1d2e3f4a5b",
  "ts": 1789012400000,
  "sid": "…",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "field": "bio",
    "old": "Top news and analysis from around the world.",
    "new": "Top news, analysis and video from around the world."
  }
}

Follow ペイロード

follow.add、follow.remove、followers.verified.add の d。

フィールド	型	意味
`user`	User	相手のアカウント (完全な User)

例

{
  "v": 1,
  "t": "follow.add",
  "op": "create",
  "id": "follow:44196397:12:add:496948",
  "ts": 1789012400000,
  "sid": "…",
  "target": {
    "id": "44196397",
    "screen_name": "elonmusk",
    "name": "Elon Musk"
  },
  "d": {
    "user": {
      "id": "12",
      "screen_name": "jack",
      "name": "jack",
      "bio": "…",
      "avatar": "https://pbs.twimg.com/profile_images/…",
      "banner": null,
      "followers": 6400000,
      "following": 4200,
      "tweets": 29000,
      "location": "",
      "url": null,
      "verified": true,
      "verified_type": "blue",
      "protected": false,
      "created_at": "2006-03-21T20:50:14Z",
      "category": null
    }
  }
}

アカウント状態ペイロード

account.status の d。状態は active (通常)、protected (承認したフォロワーにのみ投稿を公開)、suspended (X による凍結)、unavailable (停止、削除、その他の理由で閲覧不可) のいずれかです。ts は当社が変化を検知した時刻です。

フィールド	型	意味
`old`	active \| protected \| suspended \| unavailable	以前の状態
`new`	active \| protected \| suspended \| unavailable	現在の状態
`reason`	string \| null	X が示す文言 (あれば。例: `Suspended`)

例

{
  "v": 1,
  "t": "account.status",
  "op": "update",
  "id": "account:9000002:status:active>suspended:497010",
  "ts": 1789236000000,
  "sid": "…",
  "target": {
    "id": "9000002",
    "screen_name": "some_account",
    "name": "Some Account"
  },
  "d": {
    "old": "active",
    "new": "suspended",
    "reason": "Suspended"
  }
}

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 ペイロードのすべてのフィールド

例

{
  "v": 1,
  "t": "search.match",
  "op": "create",
  "id": "search:12:2097900000000000000",
  "ts": 1789012500000,
  "sid": "…",
  "target": {
    "id": "9000001",
    "screen_name": "some_trader",
    "name": "Some Trader"
  },
  "d": {
    "tweet_id": "2097900000000000000",
    "kind": "tweet",
    "text": "$SOL breaking out…",
    "lang": "en",
    "author": {
      "id": "9000001",
      "screen_name": "some_trader",
      "name": "Some Trader",
      "bio": "…",
      "followers": 1200,
      "verified": false,
      "…": "…"
    },
    "keyword": {
      "id": 12,
      "query": "($SOL OR \"Solana\") -filter:retweets",
      "label": "solana"
    },
    "author_is_target": false,
    "media": [],
    "media_items": [],
    "urls": [],
    "url": "https://x.com/some_trader/status/2097900000000000000",
    "full": true
  }
}