# Pagination

List endpoints return their results in pages. You ask for the next page with the cursor the
previous page gave you.

## Parameters

| Query parameter | Default | Description                                                         |
| --------------- | ------- | ------------------------------------------------------------------- |
| `limit`         | 20      | How many items to return on this page, from 1 to 100.               |
| `cursor`        | none    | The `next_cursor` of the previous page. Omit it for the first page. |

A `limit` outside 1 to 100, or a `cursor` Lazy cannot read, gets `400 validation_error` with
`param` naming the parameter. See [Errors](https://developers.lazyinvoice.co.il/embedded/errors/).

## Response

A page holds its items under a plural key, such as `businesses`, and a `next_cursor`:

```json
{
  "businesses": [
    {
      "biz_id": "biz_8fKq2LmZp4TnWx7RcV1a",
      "external_id": "customer-1042",
      "name": "Dana Levi Design",
      "created_at": "2026-10-02T09:14:03.512874+00:00"
    }
  ],
  "next_cursor": "eyJiaXpfaWQiOiAiYml6XzhmS3EyTG1acDRUbld4N1JjVjFhIn0="
}
```

`next_cursor` is null on the last page. Stop when it is null.

## Walking every page

```bash
curl "https://embedded-api.lazyinvoice.co.il/v1/businesses?limit=100" \
  -H "Authorization: Bearer $LAZY_API_KEY"

curl "https://embedded-api.lazyinvoice.co.il/v1/businesses?limit=100&cursor=eyJiaXpfaWQiOiAiYml6XzhmS3EyTG1acDRUbld4N1JjVjFhIn0%3D" \
  -H "Authorization: Bearer $LAZY_API_KEY"
```

Repeat the second request with each new `next_cursor` until it is null. You may change `limit`
between pages.

## Order and changes while paging

Items come in a fixed order that does not follow creation time. Each item appears at most once in a
walk. An item created during the walk may or may not appear in it. An item deleted during the walk
does not appear on later pages.

## Cursors are opaque

A cursor is a string for Lazy to read, not for you. Do not parse it, build one yourself, or rely on
its format, which may change. Always pass the `next_cursor` exactly as you received it, URL-encoded
in the query string: a cursor can contain `+`, `/` and `=`, and an unencoded `+` reaches Lazy as a
space.