Skip to main content
This reference explains how the Quivo API handles pagination and idempotency for API requests.

​
Overview

The Quivo API provides mechanisms for handling large result sets through pagination and for ensuring safe retries through idempotency. Understanding these features enables you to build reliable integrations that handle data efficiently and prevent duplicate operations.
For detailed endpoint-specific information about pagination parameters and idempotency support, see the API Reference endpoints documentation.

​
Pagination

Pagination allows you to retrieve large datasets in manageable chunks. The Quivo API supports two pagination mechanisms: offset-based pagination and cursor-based pagination.

​
Pagination Parameters

The following query parameters control pagination for endpoints that support it:
ParameterTypeDescription
pageintegerThe page number to retrieve when using offset-based pagination. Ignored if searchAfter is provided.
searchAfterstring or arrayUsed for cursor-based pagination. Pass the sort key value from the last item of the previous page to retrieve the next set of results. When sort has multiple fields, use a JSON array with values for each field. Overrides page.
pageSizeintegerThe maximum number of items to return per page. Used for both offset and cursor-based pagination. Default is 25. The maximum allowed value is 1000.
sortstringOptional sorting criteria for the results. Format is typically field:direction (for example, created:desc).
The default pageSize is 25 when not specified. Do not use very large page sizes (for example, 10000). Use page and pageSize pagination, and keep pageSize at or below the maximum allowed value of 1000.

​
Offset-Based Pagination

Offset-based pagination uses page numbers to navigate through results. Use the page parameter to specify which page to retrieve. Example: 
curl -X GET "${BASE_URL}/articles?page=1&pageSize=20" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

​
Cursor-Based Pagination

Cursor-based pagination uses a cursor value from the last item of the previous page to retrieve the next set of results. This method is more efficient for large datasets and prevents issues with data changing between page requests. To use cursor-based pagination:
  1. Include a sort parameter in your initial request to ensure consistent ordering
  2. Use the searchAfter parameter with the sort key value from the last item of the previous page
  3. The page parameter is ignored when searchAfter is provided
When sort has multiple fields, pass searchAfter as a JSON array with values corresponding to each sort field. For example, if sorting by ID and date, use ["123", "2023-10-01T12:00:00Z"].
Example: 
# First page
curl -X GET "${BASE_URL}/articles?sort=created:desc&pageSize=20" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

# Next page (using searchAfter from last item of previous response)
curl -X GET "${BASE_URL}/articles?sort=created:desc&pageSize=20&searchAfter=<SORT_KEY_VALUE_FROM_LAST_ITEM>" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"
Cursor-based pagination (searchAfter) overrides offset-based pagination (page). If you provide both parameters, only searchAfter is used.

​
Response Structure

Paginated responses are returned as arrays. The API doesn’t include pagination metadata in the response body. Response format:
  • Responses are arrays of items (for example, ArticleGetSummary[], OrderSummary[])
  • No pagination metadata fields like total, has_more, next_cursor, or page are included
  • The response body is directly the array of items
Example response structure: 
[
  {
    "<FIELD_1>": "<VALUE>",
    "<FIELD_2>": "<VALUE>",
    "<FIELD_3>": "<VALUE>"
  }
]
The actual fields and structure depend on the endpoint and resource type. See the OpenAPI specification for the exact schema of each endpoint’s response.
Determining if more pages are available: Since pagination metadata isn’t included in responses, you may need to:
  • Check if the response contains fewer items than the requested pageSize
  • Make a request for the next page and check if it returns any results

​
Finding Pagination Support

Not all endpoints support pagination. To determine if an endpoint supports pagination, see the detailed endpoint documentation in the API Reference section

​
Idempotency

Idempotency ensures that making the same request multiple times produces the same result as making it once. This is important for handling network errors, retries, and preventing duplicate operations.

​
Idempotency Support

Currently, only one endpoint supports idempotency:
  • POST /shipments/book - Books a shipment

​
How Idempotency Works

The /shipments/book endpoint uses a requestId parameter to ensure idempotency:
  • Include a unique requestId in your request
  • If you make the same request with the same requestId multiple times, the endpoint will not create a duplicate shipment
  • Instead, it returns the existing shipment that was created with that requestId
Example: 
curl -X POST "${BASE_URL}/shipments/book" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "unique-request-id-12345",
    "shipmentData": {
      ...
    }
  }'
If you make the same request with the same requestId again, you’ll receive the existing shipment instead of creating a new one. This prevents duplicate shipments from being created due to network retries or other issues.

​
Other Endpoints

For other endpoints, idempotency is not currently supported. To determine if an endpoint supports idempotency, see the detailed endpoint documentation in the API Reference section.

​
Where to go next

Now that you understand pagination and idempotency concepts, continue with these guides:

HTTP Response Codes

Understand API response codes, including errors that may occur during pagination.

Authentication

Learn about authentication required for API requests.