Pagination

Some Developer API list endpoints return paginated responses. This guide explains how to request specific pages, control page size, and read the pagination metadata returned by the API.

Overview

How pagination works across paginated Developer API endpoints.

  • Paginated endpoints use page-based navigation.
  • Use page to request a specific page number.
  • Use per_page to control how many records are returned per page.
  • Paginated responses include a meta object with pagination details.
  • Endpoints that are not paginated will return a simple collection without pagination metadata.

Request Parameters

Query parameters used for paginated list endpoints.

page

Use the page query parameter to request a specific page of results.

per_page

Use the per_page query parameter to control page size. If omitted, endpoints typically default to 10 results per page.

curl "https://api.leadpush.io/v1/workspaces/:workspace/contacts?page=2&per_page=25" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}"

Response Metadata

Fields commonly returned in the `meta` object for paginated responses.

Common Pagination Fields

FieldTypeDescription
current_pagenumberThe current page returned by the API
per_pagenumberThe number of records returned per page
totalnumberThe total number of matching records
last_pagenumberThe final page number based on the current page size
{
  "data": [
    {
      "id": "..."
    }
  ],
  "meta": {
    "current_page": 2,
    "per_page": 25,
    "total": 240,
    "last_page": 10
  }
}

Practical Guidance

Tips for integrating paginated endpoints safely.

  • Stop paging when current_page equals last_page.
  • Do not assume a fixed number of total pages across requests; new records may change totals over time.
  • Keep per_page consistent while iterating through a result set.
  • When available, combine pagination with endpoint-specific search, filtering, and sorting query parameters.
  • Check each endpoint’s page for whether it is paginated, since not all list endpoints return meta.