---
title: Pagination and idempotency
description: Continue list and Search results, and safely replay supported writes.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Pagination and idempotency

Use opaque cursors to continue lists and Search results. Use idempotency keys to retry supported writes without submitting the same logical operation twice.

## Resource list pages

**Empty list page**

```json
{
  "items": [],
  "next_cursor": null
}
```

| Field | Type | Contract |
| --- | --- | --- |
| `limit` | integer query parameter · optional | Page size. Default 50, minimum 1, maximum 100. |
| `cursor` | string query parameter · optional | Use next_cursor from the previous page. Omit on the first request. |
| `items` | array of resources | The resources in this page. May be empty. |
| `next_cursor` | string or null | Continuation token. Null means traversal is complete. |

Cursors expire after 3,600 seconds. Use the same key and list parameters for subsequent pages. URL-encode the cursor. An expired or mismatched cursor returns `400 invalid_cursor`. Do not parse or construct tokens.

## Search pages

Search uses `limit` and `cursor` in its JSON request body, and returns `results` with `next_cursor`. Its default limit is 10 and maximum is 100. Search cursors expire after 2,400 seconds, or 40 minutes.

Keep every Search request field unchanged except cursor. The token is tied to the query, filters, principals, mode, interpretation, sort, limit, result unit, and key. It preserves the index generation used for that search.

A null cursor ends traversal. Start a new search to include more recent content. Sort orders the rows within a returned page; rank remains the relevance rank.

## Idempotent writes

These operations require `Idempotency-Key`:

- Create namespace.
- Create collection.
- Add or replace file.
- Delete collection.
- Batch access rules.

**Example request header**

```http
Idempotency-Key: acme-checkout-file-version-3
```

Choose a distinct key for each logical operation. Reuse that key with the same body when retrying after an uncertain response. Engine retains it for 86,400 seconds, or 24 hours. A different body with the same key returns `409 idempotency_conflict`.

Use a new key for a replacement file or a new batch. Do not assume replay protection continues after the retention window. Inspect the resource before resubmitting an old write.

## exist_ok and retries

Namespace and collection creation also accept `exist_ok: true`. If the named resource exists, Engine returns it with `200` instead of a name conflict. This is a get-or-create operation, not an update.

Idempotency identifies one request. `exist_ok` handles an already-existing name. They serve different purposes and can be used together. See [Filter and paginate results](/engine/guides/filter-and-paginate) for connected requests.
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.