フィールド

API レスポンスで特定のデータフィールドを指定する

X API v2 は、デフォルトでは最小限のデータのみを返します。各オブジェクト type ごとに追加のデータを取得するには、fields パラメーターを使用します。

---

​

フィールドの仕組み

デフォルトでは、ポストの取得では id、text、edit_history_tweet_ids のみが返されます。より多くのデータを取得するには、リクエストにフィールドパラメータを指定してください。

# デフォルトレスポンス - 最小限のフィールド
curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $TOKEN"

# With additional fields
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,author_id" \
  -H "Authorization: Bearer $TOKEN"

---

​

利用可能なフィールドパラメータ

各オブジェクト type には、それぞれ専用のフィールドパラメータがあります。

オブジェクト	パラメータ	ドキュメント
ポスト (ツイート)	tweet.fields	ポストのフィールド
ユーザー	user.fields	ユーザーのフィールド
メディア	media.fields	メディアのフィールド
投票	poll.fields	投票のフィールド
場所	place.fields	場所のフィールド

---

​

例: ポストのフィールド

tweet.fields を使用して特定のポストのフィールドをリクエストします:

curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,lang" \
  -H "Authorization: Bearer $TOKEN"

レスポンス:

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"],
    "created_at": "2024-01-15T12:00:00.000Z",
    "lang": "en",
    "public_metrics": {
      "retweet_count": 10,
      "reply_count": 5,
      "like_count": 100,
      "quote_count": 2
    }
  }
}

---

​

例: ユーザーのフィールド

特定のユーザーフィールドを指定するには、user.fields を使用します:

curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
  -H "Authorization: Bearer $TOKEN"

レスポンス:

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "xdevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "X Developer Platformの声",
    "public_metrics": {
      "followers_count": 570842,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}

---

​

関連オブジェクトのフィールド

関連オブジェクト (ポストの作成者など) のフィールドを取得するには、次の 2 つが必要です。

1. 関連オブジェクトを含めるための expansion
2. そのオブジェクト type 用の fields パラメーター

# 投稿者の詳細を含むポストを取得
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $TOKEN"

レスポンス：

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "author_id": "2244994945"
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers",
      "description": "The voice of the X Developer Platform",
      "public_metrics": {
        "followers_count": 570842,
        "following_count": 2048
      }
    }]
  }
}

expansions について詳しく見る →

---

​

よく使われるフィールドの組み合わせ

ポスト分析

tweet.fields=created_at,public_metrics,possibly_sensitive

ユーザーのプロフィール

user.fields=created_at,description,location,public_metrics,verified

ポストの完全なコンテキスト情報

tweet.fields=created_at,author_id,conversation_id,in_reply_to_user_id,referenced_tweets
expansions=author_id,referenced_tweets.id
user.fields=username,name

メディアの詳細情報

tweet.fields=attachments
expansions=attachments.media_keys
media.fields=url,preview_image_url,alt_text,public_metrics

---

​

重要な注意事項

サブフィールドはリクエストできません。 public_metrics をリクエストすると、すべてのメトリクス (いいね、Repost、返信、引用) が返されます。public_metrics.like_count だけを個別にリクエストすることはできません。

• レスポンス内のフィールドの順序は、リクエスト時の順序と異なる場合があります
• レスポンスでフィールドが欠けている場合、その値は null または空であることを意味します
• 一部のフィールドには特定の認証が必要です (例：非公開メトリクスにはユーザーコンテキストが必要)
• 利用可能なフィールドについては、各エンドポイントのAPIリファレンスを確認してください

---

​

次のステップ

Expansions

レスポンスに関連するオブジェクトを含めます。

データ辞書

すべてのオブジェクトのフィールドの完全なリファレンスです。