> ## 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.

# ページネーション

> 検索クエリは通常、単一の API レスポンスで返せる以上の投稿にマッチします。integrate を扱う X API v2 スタンダードティアのリファレンス。

### Recent search のページネーション

#### はじめに

検索クエリは通常、単一の API レスポンスで返せる以上の投稿にマッチします。その場合、データは一連の「ページ」で返されます。ページネーションとは、データセット全体を取得するためにすべてのページをリクエストする方法を指します。

Recent search のページネーションの基本的な詳細は以下の通りです:

* Recent search エンドポイントは、クエリに対して少なくとも 1 ページで応答し、追加ページが利用可能な場合は JSON レスポンスに next\_token を含めます。マッチする投稿を受信するには、レスポンスに token が含まれなくなるまでこのプロセスを繰り返せます。

* next\_token は失効しません。同じ next\_token 値で複数回リクエストしても、いつリクエストしても同じ結果を受け取ります。

* 投稿は UTC タイムゾーンで逆時系列順に配信されます。これは個々のページ内でも、複数のページにわたっても真です:
  * 最初のレスポンスの最初の投稿は、クエリに一致する最新の投稿になります。
  * 最後のレスポンスの最後の投稿は、クエリに一致する最も古い投稿になります。

* max\_results リクエストパラメーターを使用すると、レスポンスあたりの投稿数を設定できます。デフォルトは 10 件で、最大 100 件です。

* あらゆるページネーション実装は、レスポンスペイロードから next\_token をパースし、「次ページ」の検索リクエストに含めることを含みます。これらの「次ページ」リクエストの構築方法の詳細は下記を参照してください。

Recent search エンドポイントは、2 つの基本的な使用パターンをサポートするように設計されました:

* **履歴の取得** - 対象期間から一致する投稿をリクエストします。これらは通常、履歴リサーチをサポートする一度きりのリクエストです。検索リクエストは start\_time と end\_time のリクエストパラメーターに基づけます。Recent search エンドポイントは、最新の一致投稿から始まる逆時系列順の投稿でレスポンスします。

* **ポーリング** - 前回受信した投稿以降に投稿された一致投稿をリクエストします。これらのユースケースはニアリアルタイムに焦点を当てることが多く、関心のある新しい投稿を「リッスンする」ための頻繁なリクエストを特徴とします。Recent search エンドポイントは、「ポーリング」パターンをサポートするために since\_id リクエストパラメーターを提供します。Post ID による移動を支援するため、until\_id リクエストパラメーターも利用できます。

次に履歴モードについて説明します。これは Recent search エンドポイントのデフォルトモードで、ページネーションの基礎を示します。その後、ポーリングユースケースの例について説明します。ポーリングがページネーションをトリガーするとき、検索リクエストを管理する追加のステップがあります。

#### 履歴データの取得

このセクションでは、start\_time と end\_time リクエストパラメーターを使用して、対象期間(現在は直近 7 日間に制限)から投稿を取得する方法を概説します。履歴リクエストは通常、リサーチと分析をサポートする一度きりのリクエストです。

期間のデータをリクエストすることは、Recent search エンドポイントのデフォルトモードです。検索リクエストが start\_time、end\_time、または since\_id リクエストパラメーターを指定しない場合、end\_time はデフォルトで「現在」(実際にはクエリ時刻の 30 秒前)になり、start\_time はデフォルトで 7 日前になります。

エンドポイントは、最新の投稿から始まる逆時系列順で投稿の最初の「ページ」で応答します。追加ページのデータがある場合、レスポンス JSON ペイロードには next\_token も含まれます。ページ数にかかわらず一致投稿のセット全体を収集するには、next\_token が提供されなくなるまでリクエストが行われます。

たとえば、直近 1 週間で snow というキーワードを含む投稿の初回リクエストは以下の通りです:

[https://api.x.com/2/tweets/search/recent?query=snow](https://api.x.com/2/tweets/search/recent?query=snow)

レスポンスには最新の 10 投稿と、JSON レスポンス内のこれらの "meta" 属性が含まれます:

```
"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }
```

次の 10 投稿を取得するには、この next\_token を元のリクエストに追加します。リクエストは以下のようになります:

[https://api.x.com/2/tweets/search/recent?query=snow\&next\_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql](https://api.x.com/2/tweets/search/recent?query=snow\&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql)

next\_token を探して次のリクエストに含めるプロセスは、すべての(または一定数の)投稿が収集されるか、指定数のリクエストが行われるまで繰り返せます。データの完全性(クエリのすべての一致を収集すること)がユースケースにとって重要な場合、シンプルな「request.next\_token が null になるまで繰り返す」設計で十分です。

#### ポーリングとリスニングのユースケース

このセクションでは、since\_id リクエストパラメーターで Recent search エンドポイントをポーリングして最近の投稿を取得する方法を概説します。

ポーリングユースケースでは、「関心のある新しい投稿はあるか?」というクエリが継続的、頻繁に行われます。時間に基づいてリクエストを行う履歴ユースケースとは異なり、ポーリングユースケースは通常 Post ID に基づいてリクエストを行います。

ポーリング使用パターンの中心は、すべての新しい投稿には X プラットフォームから通常昇順で「発行」される[一意の ID](/resources/fundamentals/x-ids) があることです。ある投稿の ID が別の投稿より小さい場合、その投稿の方が早く投稿されたことを意味します。

Recent search エンドポイントは Post ID による Post アーカイブの移動をサポートします。エンドポイントからのレスポンスには oldest\_id と newest\_id の Post ID が含まれます。ポーリングモードでは、これまでに受信した最大 / 最新の ID に since\_id を設定してリクエストを行います。

たとえば、snow に関する新しい投稿のクエリが 5 分ごとに行われ、最後に受信した投稿の Post ID が 10000 だったとします。ポーリング時刻になると、リクエストは以下のようになります:

[https://api.x.com/2/tweets/search/recent?query=snow\&since\_id=10000](https://api.x.com/2/tweets/search/recent?query=snow\&since_id=10000)

次に、前回のリクエスト以降に 7 件の投稿が投稿されたとします。これらすべてが単一のデータ「ページ」に収まるため、next\_token はありません。レスポンスは最新(最も新しい)投稿の Post ID を提供します:

```
"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }
```

次のポーリングクエリを行うには、この newest\_id 値を使用して次の since\_id パラメーターを設定します:

`https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000`

追加データが利用可能で next token が提供される場合、結果の最初のページからの newest\_id 値のみが必要です。各データページには newest\_id と oldest\_id 値が含まれますが、最初のページで提供された値のみが、5 分後に定期的にスケジュールされる次のポーリングリクエストに必要です。したがって、ポーリング設計を実装している、または ID 範囲で投稿を検索している場合、ページネーションロジックは少し複雑になります。

次に、さらに 18 件の一致投稿があるとします。エンドポイントはこの初期レスポンスに、この 5 分間のデータの次ページをリクエストするための完全なデータページと next\_token を含めて応答します。また、5 分後の次のポーリング間隔に必要な最新 Post ID も含めます。

```
"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }
```

この 5 分間のすべての一致データを収集するには、前のリクエストと同じ since\_id 値と共に、next\_token を次のリクエストで渡します。

[https://api.x.com/2/tweets/search/recent?query=snow\&since\\\_id=12000\&next\\\_token=fnsih9chihsnkjbvkjbsc](https://api.x.com/2/tweets/search/recent?query=snow\&since\\_id=12000\&next\\_token=fnsih9chihsnkjbvkjbsc)

```
"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }
```

この 2 回目のレスポンスは残りの 8 投稿を提供し、next\_token はありません。newest\_id の値 (12300) を更新せず、次の since\_id リクエストは最初のレスポンスの newest\_id 値に基づけます:

[https://api.x.com/2/tweets/search/recent?query=snow\&since\_id=13800](https://api.x.com/2/tweets/search/recent?query=snow\&since_id=13800)