Pagination

Pagination allows you to retrieve large sets of data in smaller, more manageable chunks. The Mambo API supports three pagination methods: offset pagination, cursor pagination, and a legacy offset pagination that is being phased out.

You can tell which pagination method an endpoint uses from its response type in the API specification:

• Offset pagination — the response type is OffsetResponseEntity.
• Cursor pagination — the response type is CursorResponseEntity.
• Legacy offset pagination — the response is a plain array of records.

Offset pagination

Offset pagination works by specifying how many records to return (limit) and how many records to skip from the start of the result set (offset). This is pagination method allows clients to access a random page (e.g. "page 7 of 23") rather than doing purely sequential navigation.

Example URI

HTTP

GET /v1/example?offset=100&limit=50 HTTP/1.1

The limit parameter defaults to 10 and the offset parameter defaults to 0.

Data model

Offset pagination returns the records in the data field and pagination metadata in the meta.page field:

JSON

{
  "meta": {
      "page": {
          "hasMore": true,
          "limit": 10,
          "offset": 100,
          "totalCount": 137
      }
  },
  "data": [
      { "object": "one" },
      { "object": "two" },
      ...
  ]
}

Each field has the following meaning:

• meta.page.limit: the maximum number of items per page that was requested.
• meta.page.offset: the zero-based index of the first item in the current page.
• meta.page.hasMore: true when at least one more page is available after this one. Use this to detect the end of the result set instead of comparing the number of returned items to limit.
• meta.page.totalCount: the total number of items matching the query, capped at 10,000. If the value is exactly 10,000, the true total may be higher.
• data: the list of records being paged.

info

The combined value of offset + limit cannot exceed 10,000. If you need to walk deeper through a result set, refine your filters.

Examples

When working with offset pagination, start at offset=0 and walk forward by adding limit to the offset until meta.page.hasMore is false:

HTTP

GET /v1/example?limit=50&offset=0 HTTP/1.1

After processing the page, fetch the next page by incrementing offset by limit:

HTTP

GET /v1/example?limit=50&offset=50 HTTP/1.1

Stop when the response has "hasMore": false.

Cursor pagination

Cursor-based pagination works by returning a pointer (cursor) to a specific item in the dataset. On subsequent requests, the server returns results after or before the given pointer (cursor). This is done by adding the pageAfter or the pageBefore query parameters to the endpoint's URI. The number of records to be returned can be changed adding the pageSize query parameter to the URL. The records will always be returned in reverse chronological order.

Example URI

To retrieve records after the cursor:

HTTP

GET /v1/webhooks?pageAfter=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

To retrieve records before the cursor:

HTTP

GET /v1/webhooks?pageBefore=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

Data model

Cursor pagination will return the records in the data field and information to help navigate to previous and next pages in the meta.page.prev and meta.page.next fields. See the example below:

JSON

{
  "meta": {
      "page": {
          "prev": "pageBeforeId",
          "next": "pageAfterId"
      }
  },
  "data": [
      { "object": "one" },
      { "object": "two" },
      ...
  ]
}

Each field has the following meaning:

• meta.page.prev: contains the cursor to use to retrieve the previous page of results. The cursor can be used with the pageBefore query parameter. This will be populated as long as the data list is not empty.
• meta.page.next: contains the cursor to use to retrieve the next page of results. The cursor can be used with the pageAfter query parameter. This will be populated as long as the data list is the same size as the pageSize query parameter.
• data: the data list being paged.

Examples

With cursor pagination, your first request won't include a cursor:

HTTP

GET /v1/webhooks?pageSize=10 HTTP/1.1

From the response, extract the meta.page.next value to get the next page:

HTTP

GET /v1/webhooks?pageAfter=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

To navigate backwards, use the meta.page.prev value:

HTTP

GET /v1/webhooks?pageBefore=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

Legacy offset pagination

Older endpoints still use a legacy offset pagination model that is being phased out. These endpoints use the page and count query parameters. The page parameter indicates which page of the results you want to fetch, starting from zero. The count parameter indicates how many records you want returned on each page.

Example URI

HTTP

GET /v1/acme/users?page=0&count=20 HTTP/1.1

Data model

Legacy offset pagination returns a plain array of records, with no metadata wrapper:

JSON

[
  { "object": "one" },
  { "object": "two" },
  ...
]

---

Related topics

• API keys
• Users