# Pagination

> Learn how pagination works in the Lev API, including cursor-based and offset-based strategies.

Source: https://www.lev.com/docs/build/pagination

Last updated: March 2026

---
## Overview

All list endpoints return results in pages. The default page size is 50 items, configurable up to 200 via the `limit` parameter.

| Strategy | When | Stability | Use Case |
|----------|------|-----------|----------|
| **Cursor** | Default (no `sort` param) | Stable — no duplicates or skips | Bulk data sync, reliable iteration |
| **Offset** | When `sort` is specified | May shift if data changes | Sorted browsing, UI tables |

## Cursor Pagination

Cursor pagination is the default. It uses an opaque, base64-encoded cursor token to track position.

**First page:**

```bash
GET /api/external/v2/deals?limit=10
```

**Response:**

```json
{
  "data": [...],
  "pagination": {
    "total": 142,
    "limit": 10,
    "cursor": null,
    "has_more": true,
    "next_cursor": "eyJpZCI6IDEwfQ=="
  }
}
```

**Next page:**

```bash
GET /api/external/v2/deals?limit=10&cursor=eyJpZCI6IDEwfQ==
```

Continue passing `next_cursor` as `cursor` until `has_more` is `false`.

> **Note:** Cursor pagination is mutually exclusive with the `sort` parameter. If you need sorted results, use offset pagination.

## Offset Pagination

When a `sort` parameter is provided, the API uses offset pagination:

```bash
GET /api/external/v2/deals?sort=-created_at&limit=10&offset=20
```

**Response:**

```json
{
  "data": [...],
  "pagination": {
    "total": 142,
    "limit": 10,
    "offset": 20,
    "has_more": true
  }
}
```

Offset pagination starts at `offset=0`. To get the next page, add `limit` to the current offset.

> **Caution:** Offset pagination can skip or duplicate items if rows are inserted or deleted between requests. For reliable bulk sync, use cursor pagination.

## Limits

| Parameter | Default | Min | Max |
|-----------|---------|-----|-----|
| `limit` | 50 | 1 | 200 |
| `offset` | 0 | 0 | — |