メインコンテンツへスキップ
expansions を使用すると、開発者はペイロード内で参照されているオブジェクトを展開できます。展開可能なオブジェクトは ID で参照されます。たとえば、Posts lookup のペイロードで返される referenced_tweets.id および author_id フィールドは、完全なオブジェクトに展開できます。特定の Post を投稿したユーザー、またはその Post に含まれるメディア、投票、プレイスに関連する fields を取得したい場合は、レスポンスでその data を受け取るために、該当する expansion クエリパラメータをリクエストに指定する必要があります。現在、Posts、Users、Lists、Spaces、Direct Message イベントオブジェクトを返す v2 エンドポイントはすべて expansions をサポートしています（以下の例を参照）。 リクエストに expansion を含めると、展開されたオブジェクトのデフォルト fields を同一のレスポンス内に含めます。これにより、個別のリクエストを行わずに同じレスポンスで追加の data を返すことができます。展開されたオブジェクトに関連する追加の fields を取得したい場合は、その展開されたオブジェクトに対応する field パラメータを、レスポンスで受け取りたいフィールドのカンマ区切りリストとともに指定できます。なお、fields はクエリで要求した順序どおりに常に返されるとは限りません。 以下の Post のペイロードには、展開可能な関連オブジェクトの参照 ID が含まれており、Post を投稿したユーザーの author_id、参照された Post の id、メディア添付の media_key などが含まれます。 
{
    "data": {
        "attachments": {
            "media_keys": ["16_1211797899316740096"]
        },
        "author_id": "2244994945",
        "id": "1212092628029698048",
        "referenced_tweets": [
            {
                "type": "replied_to",
                "id": "1212092627178287104"
            }
        ],
        "text": "私たちは、最高のAPIを実現するには、皆様と共に構築することが不可欠だと信じています。Xプラットフォーム上で開発される皆様と共に、素晴らしい一年を迎えられることを心より嬉しく思います。新年も引き続き皆様と協力できることを楽しみにしています。https://t.co/yvxdK6aOo2"
    }
}

​
Post ペイロードで利用可能な Expansions

Expansion説明
author_idPost の投稿者を表す user オブジェクトを返します
referenced_tweets.idこの Post が参照している Post オブジェクト（リツイート、引用 Tweet、または返信）を返します
edit_history_tweet_idsPost の編集履歴に含まれる Post オブジェクトを返します
in_reply_to_user_idこの Post が返信している相手の投稿者を表す user オブジェクトを返します
attachments.media_keysPost に含まれる画像・動画・GIF を表す media オブジェクトを返します
attachments.poll_idsPost に含まれる投票のメタデータを含む poll オブジェクトを返します
geo.place_idPost にタグ付けされた場所のメタデータを含む place オブジェクトを返します
entities.mentions.usernamePost で言及されたユーザーの user オブジェクトを返します
referenced_tweets.id.author_id参照されている Post の投稿者の user オブジェクトを返します

​
ユーザーペイロードで利用可能な展開

ExpansionDescription
pinned_tweet_idユーザーのプロフィールの最上部に固定されたPostを表す Post オブジェクトを返します

​
ダイレクトメッセージイベントのペイロードで利用可能な Expansions

Expansion説明
attachments.media_keysダイレクトメッセージに添付された Media オブジェクトを返します
referenced_tweets.idダイレクトメッセージ内で参照された Post オブジェクトを返します
sender_idダイレクトメッセージの作成者であり、会話への参加者を招待したユーザーを表す User オブジェクトを返します
participant_ids会話に参加または退出した参加者を表す User オブジェクトを返します

​
Spaces ペイロードで利用可能な Expansions

Expansion説明
invited_user_ids招待されたアカウントを表す User オブジェクトを返します
speaker_idsSpace で発言したアカウントを表す User オブジェクトを返します
creator_idSpace を作成したアカウントを表す User オブジェクトを返します
host_idsホストに設定されたアカウントを表す User オブジェクトを返します
topics_idsクリエイターによって設定されたトピックの説明を返します

​
リストのペイロードで利用可能な展開

展開説明
owner_idリストを作成・管理しているアカウントを表す User オブジェクトを返します

​
Media オブジェクトの展開

次のリクエストでは、デフォルトの Post フィールドに加えて、geo.place_id の展開も要求しています。 サンプルリクエスト 
{`curl 'https://api.x.com/2/tweets/:ID?expansions=geo.place_id' --header 'Authorization: Bearer $ACCESS_TOKEN'`}
サンプル応答 
{`{
  "data": {
      "geo": {
          "place_id": "01a9a39529b27f36"
      },
      "id": "ID",
      "text": "Test"
  },
  "includes": {
      "places": [
          {
              "full_name": "Manhattan, NY",
              "id": "01a9a39529b27f36"
          }
      ]
  }
}`}

​
Poll オブジェクトの展開

以下のリクエストでは、デフォルトの Post フィールドに加えて attachments.poll_ids の expansions を含めるようリクエストしています: サンプルリクエスト サンプルレスポンス 
{`{
  "data": {
      "attachments": {
          "poll_ids": ["1199786642468413448"]
      },
      "id": "1199786642791452673",
      "text": "C#"
  },
  "includes": {
      "polls": [
          {
              "id": "1199786642468413448",
              "options": [
                  {
                      "position": 1,
                      "label": "“C Sharp”",
                      "votes": 795
                  },
                  {
                      "position": 2,
                      "label": "“C Hashtag”",
                      "votes": 156
                  }
              ]
          }
      ]
  }
}`}

​
Place オブジェクトの展開

次のリクエストでは、デフォルトの Post フィールドに加えて、geo.place_id の expansion を含めるように指定しています。 サンプルリクエスト サンプルレスポンス 
{`{
  "data": {
      "geo": {
          "place_id": "01a9a39529b27f36"
      },
      "id": "ID",
      "text": "Test"
  },
  "includes": {
      "places": [
          {
              "full_name": "Manhattan, NY",
              "id": "01a9a39529b27f36"
          }
      ]
  }
}`}