Pagination

All list endpoints in the ITSM API return paginated responses. By default, results are limited to 25 items per page, but you can request up to 1,000 by setting the limit parameter. The API supports both traditional offset-based pagination and cursor-based pagination for high-volume traversal.

If you are using one of the official ITSM client libraries, pagination is handled automatically. The SDK methods return async iterators that fetch subsequent pages as you consume results.

Offset-based pagination

Offset-based pagination uses page and limit query parameters to navigate through results. Every paginated response wraps results in a data array and includes a meta.pagination object with everything you need to build paging controls.

Name
page
Type
integer
Description
The page number to retrieve (1-based). Defaults to 1.
Name
limit
Type
integer
Description
The number of items per page. Defaults to 25, maximum 1000.
Name
sortBy
Type
string
Description
The field to sort results by, e.g. createdAt, updatedAt, priority. Defaults to createdAt.
Name
sortOrder
Type
string
Description
Sort direction: asc for ascending or desc for descending. Defaults to desc.

Paginated response format

{
  "data": [
    {
      "id": "tkt_9f8a7b6c5d4e3f2a",
      "title": "VPN connection dropping",
      "status": "open",
      "priority": "high"
      // ...
    },
    {
      "id": "tkt_1a2b3c4d5e6f7g8h",
      "title": "Password reset request",
      "status": "in_progress",
      "priority": "medium"
      // ...
    }
  ],
  "meta": {
    "pagination": {
      "page": 2,
      "limit": 25,
      "total": 342,
      "totalPages": 14,
      "hasMore": true
    }
  }
}

Pagination response fields

Name
meta.pagination.page
Type
integer
Description
The current page number (1-based).
Name
meta.pagination.limit
Type
integer
Description
The number of items requested per page.
Name
meta.pagination.total
Type
integer
Description
The total number of items matching your query across all pages.
Name
meta.pagination.totalPages
Type
integer
Description
The total number of pages available. Calculated as ceil(total / limit).
Name
meta.pagination.hasMore
Type
boolean
Description
Whether there are more pages after the current one. When false, you have reached the last page.

Offset pagination examples

In this example, we request page 2 of open tickets sorted by priority in descending order, with 25 results per page. The meta.pagination object tells us there are 342 total tickets across 14 pages, and more pages remain.

GET

/v1/tickets

curl -G https://api.itsm-platform.com/v1/tickets \
  -H "Authorization: Bearer {access_token}" \
  -d page=2 \
  -d limit=25 \
  -d sortBy=priority \
  -d sortOrder=desc \
  -d status=open

Cursor-based pagination

For large datasets or real-time data where items may be inserted or removed between requests, cursor-based pagination provides stable traversal. Instead of page numbers, you pass the ID of the last (or first) item you have seen, and the API returns the next (or previous) set of results.

Cursor-based pagination is recommended when you need to iterate through the full result set without missing or duplicating items.

Name
starting_after
Type
string
Description
A ticket ID. Returns results immediately after this item in the sort order. Use the id of the last item from the previous response to fetch the next page.
Name
ending_before
Type
string
Description
A ticket ID. Returns results immediately before this item in the sort order. Use the id of the first item from the previous response to fetch the previous page.
Name
limit
Type
integer
Description
The number of items to return. Defaults to 25, maximum 1000.

You cannot combine starting_after and ending_before in the same request. You also cannot use page together with cursor parameters — choose one pagination strategy per request.

GET

/v1/tickets

curl -G https://api.itsm-platform.com/v1/tickets \
  -H "Authorization: Bearer {access_token}" \
  -d starting_after=tkt_9f8a7b6c5d4e3f2a \
  -d limit=25

Iterating through all results

When you need to process every item in a result set, loop through pages until hasMore is false. This example demonstrates fetching all open high-priority tickets using cursor-based pagination to ensure no items are skipped.

async function getAllTickets(accessToken) {
  const allTickets = []
  let cursor = undefined

  do {
    const params = new URLSearchParams({ limit: '100', status: 'open' })
    if (cursor) params.set('starting_after', cursor)

    const response = await fetch(
      `https://api.itsm-platform.com/v1/tickets?${params}`,
      { headers: { Authorization: `Bearer ${accessToken}` } },
    )

    const { data, meta } = await response.json()
    allTickets.push(...data)

    if (meta.pagination.hasMore) {
      cursor = data[data.length - 1].id
    } else {
      cursor = undefined
    }
  } while (cursor)

  return allTickets
}