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

# Pagination

> Navigate large result sets with cursor-based pagination.

## Overview

All list endpoints use **cursor-based pagination**. Cursors are opaque strings — do not attempt to parse or construct them. Simply pass the cursor from the previous response to get the next page.

## Request Parameters

| Parameter | Type    | Default | Max   | Description                        |
| --------- | ------- | ------- | ----- | ---------------------------------- |
| `limit`   | integer | `20`    | `100` | Number of items to return per page |
| `cursor`  | string  | —       | —     | Cursor from a previous response    |

## Response Shape

Paginated responses include a `pagination` object alongside the `data` array:

```json theme={null}
{
  "data": [
    { "id": "quiz_abc123", "title": "World Capitals Quiz", "..." : "..." },
    { "id": "quiz_def456", "title": "Science Trivia", "..." : "..." }
  ],
  "pagination": {
    "cursor": "eyJpZCI6InF1aXpfZGVmNDU2IiwiY3JlYXRlZF9hdCI6IjIwMjYtMDMtMTVUMTI6MDA6MDBaIn0",
    "hasMore": true
  }
}
```

| Field                | Type             | Description                                                                                  |
| -------------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `pagination.cursor`  | `string \| null` | Pass this as the `cursor` param to get the next page. `null` when there are no more results. |
| `pagination.hasMore` | `boolean`        | `true` if more results exist beyond this page.                                               |
| `pagination.total`   | `number`         | *(Optional)* Total count of items, included when available.                                  |

## Paginating Through Results

### First Request

Fetch the first page without a cursor:

```bash theme={null}
curl https://app.quiz-quail.com/api/v1/quizzes?limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Subsequent Requests

Pass the `cursor` from the previous response:

```bash theme={null}
curl "https://app.quiz-quail.com/api/v1/quizzes?limit=10&cursor=eyJpZCI6InF1..." \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Stop When Done

Stop paginating when `pagination.hasMore` is `false` or `pagination.cursor` is `null`.

## Full Example

Fetch all quizzes with pagination in JavaScript:

```javascript theme={null}
async function getAllQuizzes(apiKey) {
  const quizzes = [];
  let cursor = undefined;

  do {
    const params = new URLSearchParams({ limit: "50" });
    if (cursor) params.set("cursor", cursor);

    const response = await fetch(
      `https://app.quiz-quail.com/api/v1/quizzes?${params}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );

    const result = await response.json();
    quizzes.push(...result.data);

    cursor = result.pagination.cursor;
  } while (cursor);

  return quizzes;
}
```

<Warning>
  Fetching all results in a tight loop may trigger [rate limits](/rate-limiting). Add delays between requests if you are iterating over large datasets.
</Warning>

## Tips

* **Don't cache cursors long-term.** Cursors encode a point-in-time snapshot. If the underlying data changes significantly, a stale cursor may skip or duplicate items.
* **Use the smallest `limit` you need.** Smaller pages mean faster responses and lower memory usage on both sides.
* **Cursors are opaque.** They are base64url-encoded and their internal structure may change without notice. Never parse, modify, or construct cursors manually.