連携ガイド - X

このガイドでは、Timelines エンドポイントをアプリケーションに統合するために必要となる主要な概念を解説します。

認証

エンドポイントの要件

Endpoint	App-Only	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

フィールドとexpansions

デフォルトでは、レスポンスには id、text、edit_history_tweet_ids のみが含まれます。追加のデータを取得するには、次のようにリクエストします:

リクエスト例

cURL

curl "https://api.x.com/2/users/123/tweets?\
tweet.fields=created_at,public_metrics,author_id&\
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")

# ユーザーの投稿タイムラインを取得する
for page in client.posts.get_user_posts(
    user_id="123",
    tweet_fields=["created_at", "public_metrics", "author_id"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"],
    max_results=100
):
    for post in page.data:
        print(f"{post.text} - {post.public_metrics}")

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

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

// ページネーションを使用してユーザーの投稿タイムラインを取得する
const paginator = client.posts.getUserPosts("123", {
  tweetFields: ["created_at", "public_metrics", "author_id"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`${post.text} - ${JSON.stringify(post.public_metrics)}`);
  });
}

主要フィールド

フィールド	説明
`created_at`	ポストの作成タイムスタンプ
`public_metrics`	エンゲージメント数
`conversation_id`	スレッドの識別子
`context_annotations`	トピックの分類情報
`entities`	ハッシュタグ、メンション、URL

フィールドとExpansionsのガイド

レスポンスのカスタマイズ方法について詳しく確認する

ページネーション

タイムラインは 1 リクエストあたり最大 100 件の投稿を返します。より多くの結果が必要な場合は、ページネーションを使用してください。

仕組み

最初のリクエストで max_results を指定する
meta オブジェクトから next_token を取得する
次回のリクエストに pagination_token を含める
next_token が返されなくなるまで繰り返す

例

cURL

# 最初のリクエスト
curl "https://api.x.com/2/users/123/tweets?max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# ページネーション用トークンを使用した後続のリクエスト
curl "https://api.x.com/2/users/123/tweets?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# SDK がページネーションを自動的に処理します
all_posts = []

for page in client.posts.get_user_posts(user_id="123", max_results=100):
    if page.data:
        all_posts.extend(page.data)

print(f"Found {len(all_posts)} posts")

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

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

async function getAllTimelinePosts(userId) {
  const allPosts = [];

  // SDK は async イテレーションによりページネーションを自動的に処理します
  const paginator = client.posts.getUserPosts(userId, { maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allPosts.push(...page.data);
    }
  }

  return allPosts;
}

// 使用例
const posts = await getAllTimelinePosts("123");
console.log(`Found ${posts.length} posts`);

ページネーションガイド

ページネーションの詳細については、こちらをご覧ください

結果のフィルタリング

時間ベースのフィルタリング

Parameter	Description
`start_time`	最も古いポストのタイムスタンプ (ISO 8601)
`end_time`	最も新しいポストのタイムスタンプ (ISO 8601)
`since_id`	このIDより後の投稿を返します
`until_id`	このIDより前の投稿を返します

exclude パラメーター

結果から特定のポストの種類を除外します。

cURL

curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# リツイートと返信を除外
for page in client.posts.get_user_posts(
    user_id="123",
    exclude=["retweets", "replies"]
):
    for post in page.data:
        print(post.text)

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

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

// リツイートと返信を除外
const paginator = client.posts.getUserPosts("123", {
  exclude: ["retweets", "replies"],
});

for await (const page of paginator) {
  page.data?.forEach((post) => console.log(post.text));
}

値	説明
`retweets`	リツイートを除外
`replies`	返信を除外

ボリューム制限

各タイムラインには、取得できる最大件数が設定されています。

Endpoint	最大投稿数
User Posts timeline	直近3,200件
User Posts (exclude=replies)	直近800件
User mentions timeline	直近800件
Home timeline	3,200件または7日分

これらの上限を超える範囲の投稿をリクエストした場合、レスポンス自体は成功ステータスで返されますが、データは含まれません。

ポストの編集

投稿は30分以内に最大5回まで編集できます。タイムライン関連エンドポイントは常に最新バージョンを返します。

考慮事項

作成から30分以上経過した投稿は最終版として扱われます
リアルタイムに近いユースケースでは、編集が行われる可能性を考慮する必要があります
必要に応じて、Post lookup を使用して最終状態を確認してください

ポスト編集の基本

ポストの編集について詳しく学ぶ

ポストのメトリクス

公開メトリクス

App-Only または User Context 認証を使用しているすべての投稿で利用可能です。

{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12
  }
}

非公開メトリクス

ポストの作成者による User Context 認証が必要です:

過去30日以内の投稿にのみ利用可能
認証済みユーザーが作成した投稿に対してのみ返される
他のユーザーの投稿に対してはエラーを返す

エッジケース

非公開メトリクスとページネーション

30日より前の投稿に対して非公開メトリクスをリクエストすると、result_count: 0 の next_token を受け取る場合があります。これを回避するには:

リクエスト対象を直近30日以内に限定する
max_results を少なくとも 10 に設定する

プロモーションされていない投稿のプロモーションメトリクス

プロモーションされていない投稿に対してプロモーションメトリクスをリクエストすると、空のレスポンスが返されます。これは既知の問題です。

切り詰められたリツイートテキスト

140文字を超えるテキストを含むリツイートでは、text フィールドが切り詰められます。完全なテキストを取得するには、referenced_tweets.id の expansion を使用してください。

次のステップ

ホームタイムラインクイックスタート

ユーザーのホームフィードを取得

メンションクイックスタート

ユーザー宛てのメンションを取得

APIリファレンス

エンドポイントの詳細ドキュメント

ページネーション

大量の結果セットを処理する

​認証

​エンドポイントの要件

​非公開指標

​フィールドとexpansions

​リクエスト例

​主要フィールド

フィールドとExpansionsのガイド

​ページネーション

​仕組み

​例

ページネーションガイド

​結果のフィルタリング

​時間ベースのフィルタリング

​exclude パラメーター

​ボリューム制限

​ポストの編集

​考慮事項

ポスト編集の基本

​ポストのメトリクス

​公開メトリクス

​非公開メトリクス

​エッジケース

​次のステップ

ホームタイムラインクイックスタート

メンションクイックスタート

APIリファレンス

ページネーション

認証

エンドポイントの要件

非公開指標

フィールドとexpansions

リクエスト例

主要フィールド

ページネーション

仕組み

例

結果のフィルタリング

時間ベースのフィルタリング

exclude パラメーター

ボリューム制限

ポストの編集

考慮事項

ポストのメトリクス

公開メトリクス

非公開メトリクス

エッジケース

次のステップ