Pagination

All top-level resources in the Segment Public API return paginated requests using token based pagination. List-based API endpoints require pagination parameters to return results. If you omit pagination parameters, the requests fail validation.

Some list-based operations in the Segment Public API require pagination parameters. These parameters pass as a pagination object either through query or body parameters. If pagination is optional and not provided, the count will default to 200.

The pagination object

The pagination input object contains two main properties: cursor and count.

type Pagination {
  cursor?: string // optional cursor representing the position in a paginated list
  count: number // integer number of items to retrieve in a page, between 1 and 1000
}

You can provide pagination parameters by using either query or body parameters. The examples below show both ways to format pagination parameters.

// As query params
/warehouses?pagination.count=3&pagination.cursor=Mw%3D%3D

// as body params
{
  "pagination": {
    "count": 3,
    "cursor": "Mw=="
  }
}

Pagination response

Pagination responses include the pagination metadata that you can use to access the next page of the data. The example below shows the pagination object, which keeps track of which page was just returned, and which pages are before and after the current page.

{
  "data": {
    "warehouses": [
      ...
    ],
    "pagination": {
      "current": "MA==",
      "next": "Mw==",
      "previous": null,
      "totalEntries": 20
    }
  }
}