ホーム/ガイド/ページネーション

ページネーション

一覧エンドポイントのページネーション方式。

概要

一覧を返すエンドポイントはオフセットベースのページネーションをサポートしています。page と per_page クエリパラメータでページを指定できます。

リクエストパラメータ

以下のクエリパラメータをサポートしています：

Parameter	Type	Description
page	integer	取得するページ番号（1 始まり）。デフォルトは 1。
per_page	integer	1 ページあたりの件数（1〜100）。デフォルトは 50。

レスポンス構造

ページネーションのメタ情報はレスポンスボディの pagination オブジェクトに含まれます。

{
  "data": [
    { "id": "deal_11111111111111111111111111111111", "name": "Example Deal" },
    { "id": "deal_22222222222222222222222222222222", "name": "Another Deal" }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 142,
    "total_pages": 3
  }
}

Field	Description
page	現在のページ番号。
per_page	1 ページあたりの件数。
total	該当するリソースの総数。
total_pages	総ページ数。

使用例

# Fetch page 2 with 20 items per page
curl https://api.blueai.jp/api/v1/crm/deals?page=2&per_page=20 \
  -b cookies.txt

const res = await fetch(
  "https://api.blueai.jp/api/v1/crm/deals?page=2&per_page=20",
  { credentials: "include" },
);
const { data, pagination } = await res.json();
console.log(`Page ${pagination.page} of ${pagination.total_pages}`);

ソート

ソート可能なエンドポイントでは、sort パラメータを使ってソート順を指定できます。フォーマットは field:direction で、direction は asc（昇順）または desc（降順）です。カンマ区切りで複数フィールドのソートが可能です。

Parameter	Type	Description
sort	string	フィールド名:方向（例: name:asc）
sort (multi)	string	カンマ区切りで複数指定可能

# Sort by name ascending, then by created_at descending
curl https://api.blueai.jp/api/v1/crm/deals?sort=name:asc,created_at:desc \
  -b cookies.txt

日付範囲フィルタ

created_after / created_before パラメータで作成日の範囲を指定できます。ISO 8601 形式で指定してください。

Parameter	Type	Description
created_after	string (ISO 8601)	この日時以降に作成されたリソースのみ返却
created_before	string (ISO 8601)	この日時以前に作成されたリソースのみ返却

# Filter deals created in January 2026
curl "https://api.blueai.jp/api/v1/crm/deals?created_after=2026-01-01T00:00:00Z&created_before=2026-02-01T00:00:00Z" \
  -b cookies.txt

カーソルベースページネーション

大規模なデータセットでは、カーソルベースのページネーションが利用できます。starting_after パラメータに最後のリソースの ID を指定することで、次のページを取得できます。

Parameter	Type	Description
starting_after	string	このリソース ID の次からデータを返却
limit	integer	1ページあたりの件数（デフォルト: 50、最大: 200）

# Fetch the next page after a specific deal
curl "https://api.blueai.jp/api/v1/crm/deals?starting_after=deal_11111111111111111111111111111111&limit=50" \
  -b cookies.txt

{
  "data": [
    { "id": "deal_33333333333333333333333333333333", "name": "Next Deal" }
  ],
  "has_more": true
}

Field	Description
has_more	次のページが存在するかどうか

パフォーマンスオプション

skip_total=true を指定すると、total のカウントクエリをスキップしてレスポンス速度を向上できます。この場合、total は -1 を返します。

Parameter	Type	Description
skip_total	boolean	true にすると total カウントをスキップ（total=-1 を返却）

# Skip total count for faster response
curl "https://api.blueai.jp/api/v1/crm/deals?page=1&per_page=50&skip_total=true" \
  -b cookies.txt

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": -1,
    "total_pages": -1
  }
}