ページネーション

コレクション系エンドポイントは、カーソルベースのページネーション を採用しています。並び順は 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

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

クエリパラメータ

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

レスポンス形状

{
  "data": [ ... ],
  "meta": {
    "request_id": "req_xxxxx",
    "next_cursor": "eyJpZCI6IjdkZmE...",
    "has_more": true
  }
}

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

ドリルスルー例

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

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 が重複することはありません。

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

はじめに

コンセプト