> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 統合ガイド

> このガイドでは、Timelines エンドポイントをアプリケーションに統合するために必要な主要概念を扱います。timelines を扱う X API v2 スタンダードティアのリファレンス。

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

***

## 認証

### エンドポイントの要件

| Endpoint               | App-Only | User Context |
| :--------------------- | :------- | :----------- |
| User Posts timeline    | ✓        | ✓            |
| User mentions timeline | ✓        | ✓            |
| Home timeline          | —        | ✓(必須)        |

### 非公開メトリクス

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

<Warning>
  以下のフィールドは 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`
</Warning>

***

## Fields と expansions

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

### リクエスト例

<CodeGroup dropdown>
  ```bash cURL theme={null}
  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"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  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)}`);
    });
  }
  ```
</CodeGroup>

### 主なフィールド

| Field                 | Description      |
| :-------------------- | :--------------- |
| `created_at`          | 投稿作成タイムスタンプ      |
| `public_metrics`      | エンゲージメント数        |
| `conversation_id`     | スレッド識別子          |
| `context_annotations` | トピック分類           |
| `entities`            | ハッシュタグ、メンション、URL |

<Card title="Fields と expansions ガイド" icon="sliders" href="/x-api/fundamentals/fields">
  レスポンスのカスタマイズについて詳しく学ぶ
</Card>

***

## ページネーション

タイムラインはリクエストあたり最大 100 投稿を返します。より大規模な結果セットにはページネーションを使用します。

### しくみ

1. `max_results` を指定して最初のリクエストを行う
2. `meta` オブジェクトから `next_token` を取得
3. 次のリクエストに `pagination_token` を含める
4. `next_token` が返されなくなるまで繰り返す

### 例

<CodeGroup dropdown>
  ```bash cURL theme={null}
  # 最初のリクエスト
  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"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  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")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

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

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

    // SDK が非同期イテレーションでページネーションを自動処理
    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`);
  ```
</CodeGroup>

<Card title="ページネーションガイド" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination" width="24" height="24" data-path="icons/xds/icon-arrow-right.svg">
  ページネーションについて詳しく学ぶ
</Card>

***

## 結果のフィルタリング

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

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

### Exclude パラメーター

特定の投稿タイプを結果から除外します:

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # retweet と reply を除外
  for page in client.posts.get_user_posts(
      user_id="123",
      exclude=["retweets", "replies"]
  ):
      for post in page.data:
          print(post.text)
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

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

  // retweet と reply を除外
  const paginator = client.posts.getUserPosts("123", {
    exclude: ["retweets", "replies"],
  });

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

| Value      | Effect      |
| :--------- | :---------- |
| `retweets` | retweet を除外 |
| `replies`  | reply を除外   |

***

## ボリューム制限

各タイムラインには最大取得制限があります:

| Endpoint                     | Maximum Posts   |
| :--------------------------- | :-------------- |
| User Posts timeline          | 最新 3,200 件      |
| User Posts (exclude=replies) | 最新 800 件        |
| User mentions timeline       | 最新 800 件        |
| Home timeline                | 3,200 件または 7 日間 |

<Note>
  これらの制限を超えて投稿をリクエストすると、データを含まない成功レスポンスが返ります。
</Note>

***

## 投稿の編集

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

### 考慮事項

* 30 分以上経過した投稿は最終バージョンを表します
* ニアリアルタイムユースケースでは編集の可能性を考慮してください
* 必要に応じて Post lookup を使用して最終状態を確認します

<Card title="Edit Posts の基礎" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1" href="/x-api/fundamentals/edit-posts" width="24" height="24" data-path="icons/xds/icon-history.svg">
  投稿の編集について詳しく学ぶ
</Card>

***

## 投稿メトリクス

### 公開メトリクス

App-Only または User Context 認証で、すべての投稿で利用可能:

```json theme={null}
{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12,
    "bookmark_count": 34,
    "impression_count": 15200
  }
}
```

### 非公開メトリクス

投稿の作成者からの User Context 認証が必要です:

* 直近 30 日間の投稿でのみ利用可能
* 認証ユーザーが作成した投稿でのみ返されます
* 他のユーザーの投稿ではエラーを返します

***

## エッジケース

<Accordion title="非公開メトリクスとページネーション">
  30 日以上前の投稿で非公開メトリクスをリクエストする場合、`result_count: 0` と共に `next_token` が返されることがあります。これを避けるには:

  * リクエストを直近 30 日間内に保つ
  * `max_results` を少なくとも 10 にする
</Accordion>

<Accordion title="非プロモート投稿の promoted metrics">
  プロモートされていない投稿に対して promoted metrics をリクエストすると、空のレスポンスが返されます。これは既知の問題です。
</Accordion>

<Accordion title="切り詰められた Retweet テキスト">
  140 文字を超えるテキストを含む Retweet では、text フィールドが切り詰められます。完全なテキストを取得するには `referenced_tweets.id` expansion を使用します。
</Accordion>

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="Home timeline クイックスタート" icon="house" href="/x-api/posts/timelines/quickstart/reverse-chron-quickstart">
    ユーザーのホームフィードを取得
  </Card>

  <Card title="メンション クイックスタート" icon="at" href="/x-api/posts/timelines/quickstart/user-mention-quickstart">
    ユーザーのメンションを取得
  </Card>

  <Card title="API リファレンス" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-posts" width="24" height="24" data-path="icons/xds/icon-code.svg">
    エンドポイントの完全なドキュメント
  </Card>

  <Card title="ページネーション" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination" width="24" height="24" data-path="icons/xds/icon-arrow-right.svg">
    大規模な結果セットを処理
  </Card>
</CardGroup>