Pagination

🚧

Deprecation Notice

Since October 2023, all List API endpoints support new cursor-based pagination.

Offset-based pagination with page query parameter is getting deprecated. In the transition period, endpoints that supported the old offset-based pagination will support both offset-based and cursor-based pagination.

Client libraries after a specific version noted below will support only cursor-based pagination.

Cursor-based Query Parameters

Query parameterDescription
cursorRepresents a value that fetches the next page of objects. To fetch the next page of objects, set cursor to the value received in the previous page response.
per_pageRepresents the maximum number of objects returned in a single page. Defaults to 200 if per_page is not passed or if per_page is set higher than 200.

Cursor-based Response Parameters

Response parameterDescription
cursorUse this value with the next API query to fetch the next page of objects.
has_moreSet to true if there are more objects to list in the next page or false if there are no more objects to list.

Example

Listing the first page of Customers:

curl -X GET "https://api.chartmogul.com/v1/customers?per_page=50" \
     -u YOUR_API_KEY:
ChartMogul::Customer.all(per_page: 50)
ChartMogul.Customer.all(config, {
  per_page: 50,
});
ChartMogul\Customer::all([
  "per_page" => 50
]);
api.ListCustomers(&cm.ListCustomersParams{
  Cursor: cm.Cursor{PerPage: 50},
})
chartmogul.Customer.all(config, per_page=50)

Response:

{
  "entries": [
    ...
  ],
  "cursor": "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more": true
}
#<ChartMogul::Customers:0x007fe7e09ca7c8 
  @entries=[
    ...
  ], 
  @cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  @has_more=true
>
{
  entries: [
    ...
  ],
  cursor: "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  has_more: true
}
ChartMogul\Customers::__set_state(array(
  "entries" => Doctrine\Common\Collections\ArrayCollection::__set_state(array(
    "elements" => array(
      ...
    )
  )),
  "cursor" => "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more" => true
));
(*chartmogul.Customers)(0xc042088b40)({
  Entries: ([]*chartmogul.Customer)(
    ...
  ),
  Cursor: (string) (len=44) "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  HasMore: (bool) true
})
Customers(
  entries=[...],
  cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  has_more=True
)

Listing the next page of Customers:

curl -X GET "https://api.chartmogul.com/v1/customers?per_page=50&cursor=AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k" \
     -u YOUR_API_KEY:
ChartMogul::Customer.all(
  per_page: 50,
  cursor: "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
)
ChartMogul.Customer.all(config, {
  per_page: 50,
  cursor: "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
});
ChartMogul\Customer::all([
  "per_page" => 50,
  "cursor" => "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k"
]);
api.ListCustomers(&cm.ListCustomersParams{
  Cursor: cm.Cursor{
    PerPage: 50,
    Cursor:  "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  },
})
chartmogul.Customer.all(
  config, per_page=50, cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k"
)

Client Libraries

Our client libraries will stop supporting old the offset-based pagination. Here's the list of client library versions after which only cursor-based pagination is supported.

Client libraryThe first version supporting only cursor-based pagination
Ruby4.0.0
Node.js3.0.0
PHP6.0.0
Gov4
Python4.0.0