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

# ページネーション

> カーソル形式・limit 範囲・対象エンドポイント

コレクション系エンドポイントは、**カーソルベースのページネーション** を採用しています。並び順は `created_at DESC, id DESC`（新しいものが先頭）です。前回のレスポンスで得た `next_cursor` を、次のリクエストで `?cursor=` として渡します。ページ番号やオフセットは存在しません。

## ページネーション対応エンドポイント

以下のエンドポイントは `meta` に `next_cursor` と `has_more` を含みます。

* `GET /v1/videos`
* `GET /v1/videos/{id}/analyses`
* `GET /v1/deals`
* `GET /v1/deals/{id}/activities`
* `GET /v1/deals/{id}/scorings`

## 非ページネーションコレクション

以下のエンドポイントは 1 回のレスポンスで全件を返します。`cursor` や `limit` パラメータは受け付けません。

* `GET /v1/members`
* `GET /v1/webhooks`
* `GET /v1/videos/{id}/transcript`
* `GET /v1/videos/{id}/events`

<Warning>
  上記エンドポイントに `?cursor=...` や `?limit=...` を渡しても、警告なく無視されます（エラーにはなりません）。`limit` を指定したのに件数が絞られない場合は、このエンドポイント群に該当している可能性があります。
</Warning>

## クエリパラメータ

| パラメータ    | デフォルト | 範囲      | 備考                                        |
| -------- | ----- | ------- | ----------------------------------------- |
| `limit`  | `25`  | `1–100` | 範囲外の値は `422 validation_failed` を返します      |
| `cursor` | —     | —       | 不透明な base64url 文字列。そのまま渡してください。パース・加工は不可。 |

## レスポンス形状

```json theme={null}
{
  "data": [ ... ],
  "meta": {
    "request_id": "req_xxxxx",
    "next_cursor": "eyJpZCI6IjdkZmE...",
    "has_more": true
  }
}
```

次ページがない場合、`has_more` は `false`、`next_cursor` は `null` になります。

## ドリルスルー例

ループ判定はカーソル文字列ではなく `has_more` を使うのが安全です。将来レスポンス形状が変わっても動作が安定します。

```bash theme={null}
CURSOR=""
while true; do
  URL="$LYMO_BASE/v1/videos?limit=10"
  [ -n "$CURSOR" ] && URL="$URL&cursor=$CURSOR"

  RESP=$(curl -s "$URL" -H "Authorization: Bearer $LYMO_KEY")
  echo "$RESP" | jq .data

  HAS_MORE=$(echo "$RESP" | jq -r .meta.has_more)
  [ "$HAS_MORE" != "true" ] && break
  CURSOR=$(echo "$RESP" | jq -r .meta.next_cursor)
done
```

## 不正なカーソル

形式不正・パース不能な `cursor` は **警告なくページ 1 にフォールバック** します。これは意図的な挙動です。カーソル形式は API のバージョン間で変わる可能性があるため、古いクライアントビルドから渡された失効カーソルで処理が壊れないようにしています。

古いカーソルを検知したい場合は、先頭要素の ID を期待値と比較するか、より堅牢な設計として、直近の成功カーソルをタイムスタンプ付きで保存し、定期的に最初から取り直してください。

## 書き込みとの同時実行時の安定性

カーソルは `(created_at, id)` に対するキーセットページネーションを使っています。結果として:

* **ページング開始後に作成された項目** は、新規クエリの最初のページに出現します。途中のページに紛れ込むことはありません。
* **ページング中に削除された項目** は、ページがスキップされる形で現れます。削除箇所の次の項目が返り、以前の ID が重複することはありません。
* **ページ間で ID が重複することはありません。**

オフセットページネーションよりも長時間ドリルスルーに対して安全ですが、全件数は途中で取得できないというトレードオフがあります。