> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.quivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination & Idempotency

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.

<Info>
  For detailed endpoint-specific information about pagination parameters and idempotency support, see the [API Reference endpoints](/api-reference/#tag) documentation.
</Info>

## 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:

| Parameter     | Type            | Description                                                                                                                                                                                                                              |
| ------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`        | integer         | The page number to retrieve when using offset-based pagination. Ignored if `searchAfter` is provided.                                                                                                                                    |
| `searchAfter` | string or array | Used 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`. |
| `pageSize`    | integer         | The 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`.                                                                                  |
| `sort`        | string          | Optional sorting criteria for the results. Format is typically `field:direction` (for example, `created:desc`).                                                                                                                          |

<Warning>
  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`.
</Warning>

### Offset-Based Pagination

Offset-based pagination uses page numbers to navigate through results. Use the `page` parameter to specify which page to retrieve.

**Example:**

```bash theme={null}
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

<Note>
  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"]`.
</Note>

**Example:**

```bash theme={null}
# 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>"
```

<Note>
  Cursor-based pagination (`searchAfter`) overrides offset-based pagination (`page`). If you provide both parameters, only `searchAfter` is used.
</Note>

### 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:**

```json theme={null}
[
  {
    "<FIELD_1>": "<VALUE>",
    "<FIELD_2>": "<VALUE>",
    "<FIELD_3>": "<VALUE>"
  }
]
```

<Note>
  The actual fields and structure depend on the endpoint and resource type. See the [OpenAPI specification](https://s3-eu-west-1.amazonaws.com/quivo-connector-prod-api-docs/swagger.json) for the exact schema of each endpoint's response.
</Note>

**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](/api-reference/#tag) 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:**

```bash theme={null}
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": {
      ...
    }
  }'
```

<Note>
  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.
</Note>

### 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](/api-reference/#tag) section.

## Where to go next

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

<CardGroup cols={2}>
  <Card title="HTTP Response Codes" icon="code" href="/api-reference/http-response-codes">
    Understand API response codes, including errors that may occur during pagination.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn about authentication required for API requests.
  </Card>
</CardGroup>