統合ガイド

このガイドでは、Post lookup エンドポイントをアプリケーションに統合する際に必要な主要概念を扱います。

認証

すべての X API v2 エンドポイントは認証を必要とします。ユースケースに合わせて方式を選択してください:

Method	Best for	Can access private metrics?
OAuth 2.0 App-Only	サーバー間、公開データ	No
OAuth 2.0 Authorization Code with PKCE	ユーザー向けアプリ	Yes(認可済みユーザーの投稿)
OAuth 1.0a User Context	従来の統合	Yes(認可済みユーザーの投稿)

App-Only 認証

公開投稿データには Bearer Token を使用します:

cURL

curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# ID で単一の投稿を取得
response = client.posts.get("1234567890")
print(response.data)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.posts.get("1234567890");
console.log(response.data);

User Context 認証

非公開メトリクスにアクセスするには、投稿の作成者の代理で認証します:

以下のフィールドは User Context 認証が必要です:

tweet.fields.non_public_metrics
tweet.fields.promoted_metrics
tweet.fields.organic_metrics
media.fields.non_public_metrics
media.fields.promoted_metrics
media.fields.organic_metrics

Fields と expansions

X API v2 はデフォルトで最小限のデータを返します。fields と expansions を使って必要なものだけをリクエストします。

デフォルトレスポンス

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"]
  }
}

利用可能なフィールド

tweet.fields

Field	Description
`created_at`	投稿作成タイムスタンプ
`author_id`	作成者のユーザー ID
`public_metrics`	いいね、リツイート、返信、引用数
`entities`	ハッシュタグ、メンション、URL、キャッシュタグ
`attachments`	メディアキー、poll ID
`conversation_id`	スレッド識別子
`context_annotations`	トピック/エンティティ分類
`in_reply_to_user_id`	返信先のユーザー
`lang`	検出された言語
`source`	投稿クライアント
`possibly_sensitive`	センシティブコンテンツフラグ
`reply_settings`	誰が返信できるか

user.fields(author_id expansion が必要)

Field	Description
`username`	@ハンドル
`name`	表示名
`profile_image_url`	アバター URL
`verified`	認証ステータス
`description`	自己紹介
`public_metrics`	フォロワー / フォロー数
`created_at`	アカウント作成日

media.fields(attachments.media_keys expansion が必要)

Field	Description
`url`	メディア URL
`preview_image_url`	サムネイル URL
`type`	photo、video、animated_gif
`duration_ms`	動画の再生時間
`height`, `width`	サイズ
`alt_text`	アクセシビリティテキスト

フィールド付きの例

cURL

curl "https://api.x.com/2/tweets/1234567890?\
tweet.fields=created_at,public_metrics,entities&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 追加フィールドと expansions 付きで投稿を取得
response = client.posts.get(
    "1234567890",
    tweet_fields=["created_at", "public_metrics", "entities"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"]
)

print(response.data)
print(response.includes)  # 展開された user と media オブジェクトを含む

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.posts.get("1234567890", {
  tweetFields: ["created_at", "public_metrics", "entities"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
});

console.log(response.data);
console.log(response.includes); // 展開された user と media オブジェクトを含む

投稿の編集

投稿は作成から 30 分以内に最大 5 回まで編集できます。

しくみ

各編集は新しい投稿 ID を作成します
edit_history_tweet_ids にはすべてのバージョンが古い順に含まれます
エンドポイントは常に最新バージョンを返します

レスポンス例

{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}

30 分の編集期間経過後に取得した投稿は最終バージョンを表します。リアルタイムユースケースでは、公開直後の投稿がまだ編集される可能性があることに注意してください。

エラー処理

一般的なエラー

Status	Error	Solution
400	無効なリクエスト	パラメーターの形式を確認
401	Unauthorized	認証情報を検証
403	Forbidden	App の権限を確認
404	Not Found	投稿が削除されたか存在しない
429	Too Many Requests	待機してリトライ(レート制限参照)

削除済みまたは保護された投稿

投稿が削除されているか、フォローしていない保護アカウントの投稿の場合:

単一投稿の lookup は 404 を返します
複数投稿の lookup では結果からその投稿が省略され、errors 配列に含まれます

レスポンス例

{
  "data": [
    { "id": "1234567890", "text": "Available post" }
  ],
  "errors": [
    {
      "resource_id": "1234567891",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [1234567891]."
    }
  ]
}

ベストプラクティス

リクエストをバッチ化

複数投稿エンドポイントを使って一度に最大 100 件の投稿を取得し、API 呼び出しを削減します。

必要なフィールドのみリクエスト

必要なフィールドのみを指定して、レスポンスサイズと処理時間を最小化します。

レスポンスをキャッシュ

同じコンテンツへの繰り返しリクエストを減らすため、投稿データをローカルにキャッシュします。

編集を処理

リアルタイムアプリでは、30 分の編集期間後に投稿を再取得することを検討してください。

次のステップ

API リファレンス

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

データディクショナリ

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

サンプルコード

動作するコード例

エラー処理

エラーをグレースフルに処理

Getting Started

Products

Fundamentals

Partners & Customers

Resources

認証

App-Only 認証

User Context 認証

Fields と expansions

デフォルトレスポンス

利用可能なフィールド

フィールド付きの例

投稿の編集

しくみ

レスポンス例

エラー処理

一般的なエラー

削除済みまたは保護された投稿

ベストプラクティス

リクエストをバッチ化

必要なフィールドのみリクエスト

レスポンスをキャッシュ

編集を処理

次のステップ

API リファレンス

データディクショナリ

サンプルコード

エラー処理

​認証

​App-Only 認証

​User Context 認証

​Fields と expansions

​デフォルトレスポンス

​利用可能なフィールド

​フィールド付きの例

​投稿の編集

​しくみ

​レスポンス例

​エラー処理

​一般的なエラー

​削除済みまたは保護された投稿

​ベストプラクティス

リクエストをバッチ化

必要なフィールドのみリクエスト

レスポンスをキャッシュ

編集を処理

​次のステップ

API リファレンス

データディクショナリ

サンプルコード

エラー処理

認証

App-Only 認証

User Context 認証

Fields と expansions

デフォルトレスポンス

利用可能なフィールド

フィールド付きの例

投稿の編集

しくみ

レスポンス例

エラー処理

一般的なエラー

削除済みまたは保護された投稿

ベストプラクティス

次のステップ