Fields

X API v2 のエンドポイントには、各オブジェクトごとにレスポンスから必要なデータだけを選択できる一連のパラメータ群である fields が用意されています。

デフォルトでは、Post オブジェクトは id と text に加え、2022年9月29日以降に作成された Post については edit_history_tweet_ids のみを返します。Post の作成日時や公開メトリクスが必要な場合は、tweet.fields パラメータを使用して明示的にリクエストしてください。これにより、ユースケースに応じて必要な fields のみに絞り込め、より柔軟にカスタマイズできます。例として、次のクエリ文字列をリクエストに含めます:

?tweet.fields=created_at,public_metrics

各オブジェクトには、そのオブジェクトに紐づく fields を個別に指定してリクエストするための専用パラメータがあります。現在利用可能な fields パラメータは次のとおりです:

• Post → tweet.fields
• User → user.fields
• Media → media.fields
• Poll → poll.fields
• Place → place.fields

特定のオブジェクトを主に返すエンドポイントを使用する場合は、対応する fields パラメータを使用し、取得したい field 名をカンマ区切りで値に指定するだけで、レスポンスにそれらの fields を含められます。

​

例

GET /tweets/search/recent エンドポイントを使用する場合、レスポンスには主に Tweet オブジェクト が含まれます。fields パラメータを指定しないと、デフォルトの id と text のみが返されます。レスポンスで返される Post の公開メトリクスを取得したい場合は、リクエストに tweet.fields パラメータを含め、値に public_metrics を指定してください。

このリクエストは次のとおりです。このリクエストを使用する場合は、必ず $BEARER_TOKEN をBearer Token に置き換え、コマンドラインツールから送信してください。

curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

ターミナルでこのリクエストを送信すると、返される各Postには以下のfieldsが含まれます。

{
   "data": {
       "id": "1263150595717730305",
       "public_metrics": {
           "retweet_count": 12,
           "reply_count": 14,
           "like_count": 49,
           "quote_count": 7
       },
       "text": "新しいTweet設定、見ていただけましたか？👀\n\nAPIでこの機能をどのように、なぜ使いたいと思うか、ぜひ教えてください。詳細を確認して、ご意見をお聞かせください👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER"
   }
}

エンドポイントが返す一次オブジェクトに関連付けられた二次オブジェクトから特定の fields を取得したい場合は、追加で expansions パラメーターを含める必要があります。たとえば、先ほどと同じ GET search/tweets/recent エンドポイントを使用していて、作者のプロフィールの自己紹介文を取得したい場合は、リクエストに expansions=author_id と user.fields=description を指定する必要があります。以下はその例です。このリクエストを試す場合は、コマンドラインツールに貼り付ける前に、$BEARER_TOKEN をご自身の Bearer Token に置き換えてください。

  curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics&expansions=author_id&user.fields=description' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

これをリクエストで指定すると、配信される各Postには以下のfieldsが含まれ、関連するユーザーオブジェクトのデフォルトおよび指定したfieldsがincludes内に返されます。ユーザーオブジェクトは、tweet.author_id と users.id のfieldsを照合することで、対応するPostにマッピングできます。

{
  "data": [
    {
      "id": "1263150595717730305",
      "author_id": "2244994945",
      "text": "新しいTweet設定、見ていただけましたか？👀\n\nAPIでこの機能をどのように、なぜ使いたいか教えてください。詳細を確認して、ご意見をお聞かせください👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER",
      "public_metrics": {
        "retweet_count": 12,
        "reply_count": 13,
        "like_count": 51,
        "quote_count": 7
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "TwitterDev",
        "description": "#TwitterDevチームの公式アカウント。#TwitterAPIに関する最新情報、ニュース、イベント情報をお届けします。",
        "name": "Twitter Dev"
      }
    ]
  }
}

特定のサブフィールド（例：public_metrics.retweet_count）をリクエストすることはできません。トップレベルのフィールド（public_metrics）を指定すると、すべてのサブフィールドが返されます。各エンドポイントのAPIリファレンスページのパラメータ表に、リクエスト可能なすべての fields を掲載しています。

fields の完全な一覧はオブジェクトモデルに掲載されています。エンドポイントの主要リソースではないオブジェクトに対して fields を取得・展開したい場合は、expansions パラメータを fields と併用してください。