Home/Guides/Pagination

Pagination

How pagination works on list endpoints.

Overview

List endpoints support offset-based pagination. Use the page and per_page query parameters to navigate through results.

Request Parameters

The following query parameters are supported:

Parameter	Type	Description
page	integer	The page number to retrieve (1-indexed). Defaults to 1.
per_page	integer	Number of items per page (1–100). Defaults to 50.

Response Structure

Pagination metadata is included in the pagination object in the response body.

{
  "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	The current page number.
per_page	The number of items per page.
total	The total number of matching resources.
total_pages	The total number of pages.

Example

# 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}`);

Sorting

For sortable endpoints, use the sort parameter to specify the sort order. The format is field:direction where direction is asc (ascending) or desc (descending). Multiple fields can be sorted using comma separation.

Parameter	Type	Description
sort	string	field:direction (e.g. name:asc)
sort (multi)	string	Multiple fields via comma

# 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

Date Range Filters

Use created_after / created_before parameters to filter by creation date range. Specify in ISO 8601 format.

Parameter	Type	Description
created_after	string (ISO 8601)	Only return resources created after this timestamp
created_before	string (ISO 8601)	Only return resources created before this timestamp

# 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

Cursor-based Pagination

For large datasets, cursor-based pagination is available. Pass the ID of the last resource to the starting_after parameter to fetch the next page.

Parameter	Type	Description
starting_after	string	Return data starting after this resource ID
limit	integer	Number of items per page (default: 50, max: 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	Whether there are more pages available

Performance Options

Use skip_total=true to skip the total count query for faster responses. When enabled, total returns -1.

Parameter	Type	Description
skip_total	boolean	Set to true to skip total count (total=-1 in response)

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