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 parameter	Description
cursor	Represents 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_page	Represents 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 parameter	Description
cursor	Use this value with the next API query to fetch the next page of objects.
has_more	Set 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)

{
  "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 library	The first version supporting only cursor-based pagination
Ruby	4.0.0
Node.js	3.0.0
PHP	6.0.0
Go	v4
Python	4.0.0