メインコンテンツへスキップ
このガイドでは、User lookup エンドポイントをアプリケーションに統合する際に必要となる主要な概念について説明します。

​
認証

すべての X API v2 のエンドポイントは認証が必須です。ユースケースに合った認証方法を選択してください。
方法適した用途プライベートメトリクスにアクセス可能か
OAuth 2.0 App-Onlyサーバー間、公開データいいえ
OAuth 2.0 Authorization Code with PKCEエンドユーザー向けの Appはい (認可されたユーザーのデータ)
OAuth 1.0a User Contextレガシーな統合はい (認可されたユーザーのデータ)

​
App-only 認証

公開ユーザーデータの取得にはベアラートークンを使用します。
cURL
curl "https://api.x.com/2/users/by/username/XDevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
User Context 認証

認証済みユーザーエンドポイント (/2/users/me) に必要です:
cURL
curl "https://api.x.com/2/users/me" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
/2/users/me エンドポイントは User Context 認証でのみ利用できます。App-Only トークンではエラーが返されます。

​
フィールドとexpansions

X API v2 では、既定では最小限のデータしか返されません。必要な情報だけを取得するために、fields と expansions を使用してください。

​
既定のレスポンス

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

​
利用可能なフィールド

FieldDescription
created_atアカウント作成日時
descriptionユーザーの自己紹介
entities自己紹介文内の解析済み URL
locationユーザーが設定した位置情報
pinned_tweet_idピン留めされたポストの ID
profile_image_urlアバターの URL
protectedアカウントが非公開かどうか
public_metricsフォロワー数／フォロー数
urlウェブサイトの URL
verified認証ステータス
withheld保留情報
FieldDescription
created_atポスト作成日時
textポストの内容
public_metricsエンゲージメント数
entitiesハッシュタグ、メンション、URL

​
フィールドを指定した例

cURL
curl "https://api.x.com/2/users/by/username/XDevelopers?\
user.fields=created_at,description,public_metrics,verified&\
expansions=pinned_tweet_id&\
tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
Expansions を含めたレスポンス

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "verified": true,
    "pinned_tweet_id": "1234567890",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052
    }
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "Welcome to the X Developer Platform!",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

フィールドとexpansionsのガイド

レスポンスのカスタマイズについて詳しく学ぶ

​
バッチによる一括取得

1回のリクエストで複数のユーザーを取得します。
cURL (by IDs)
curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"
バッチリクエストで取得できるのは最大100ユーザーまでです。より大きなデータセットには、複数のリクエストを使用してください。

​
エラー処理

​
一般的なエラー

StatusErrorSolution
400無効なリクエストパラメータの書式を確認してください
401未認証認証情報を確認してください
403禁止されていますApp の権限を確認してください
404見つかりませんユーザーが存在しないか、凍結されています
429リクエストが多すぎます待機してから再試行してください (レート制限を参照)

​
凍結または削除されたユーザー

ユーザーが凍結または削除されている場合は、次のように動作します。
  • 単一ユーザー検索は 404 を返します
  • 複数ユーザー検索では、そのユーザーは結果に含まれず、代わりに errors 配列にエントリが追加されます
{
  "data": [
    { "id": "2244994945", "username": "XDevelopers" }
  ],
  "errors": [
    {
      "resource_id": "1234567890",
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with id: [1234567890]."
    }
  ]
}

​
非公開ユーザー

フォローしていない非公開アカウントの場合:
  • 基本情報 (id、name、username) は取得可能
  • 非公開コンテンツ (固定されたポスト) が制限される場合がある
  • protected: true がアカウントのステータスを示します

​
ベストプラクティス

バッチリクエスト

最大 100 ユーザーを一度に取得できるマルチユーザーエンドポイントを使用して、API 呼び出し回数を削減します。

必要なフィールドだけをリクエスト

レスポンスサイズを最小限に抑えるため、必要なフィールドだけを指定します。

ユーザーデータをキャッシュ

ユーザープロフィールをローカルにキャッシュして、同様のリクエストを繰り返す回数を減らします。

エラーを適切に処理

バッチレスポンス内に部分的なエラーが含まれていないか確認します。

​
次のステップ

APIリファレンス

エンドポイントの完全なドキュメント

データ辞書

利用可能なすべてのオブジェクトとフィールド

サンプルコード

実行可能なコード例

エラーハンドリング

エラーを適切に処理する