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

# Pagination

> How list endpoints in the ArcenPay API paginate — cursor-based pagination, limits, search, and the nextCursor contract.

ArcenPay list endpoints use **cursor-based pagination**. You request a page size with `limit`, read the returned `nextCursor`, and pass it back as `cursor` on the next request. Cursor pagination is stable even when new records arrive between requests — unlike `page`/`offset` pagination.

## Common query parameters

| Parameter | Type    | Default | Maximum | Description                                                                                                 |
| --------- | ------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `limit`   | integer | 50      | 200     | Number of results to return per page.                                                                       |
| `cursor`  | string  | —       | —       | Opaque cursor from the previous response's `nextCursor`. Passing an empty string returns `400`.             |
| `search`  | string  | —       | —       | Case-insensitive search across key identity fields (name, email, wallet). Available on companies and users. |

## Response contract

List endpoints return this shape:

```json theme={null}
{
  "data": [
    { "id": "cm_abc", "name": "Acme" }
  ],
  "count": 1,
  "nextCursor": "cm_xyz"
}
```

| Field        | Type           | Description                                                              |
| ------------ | -------------- | ------------------------------------------------------------------------ |
| `data`       | array          | The page of results.                                                     |
| `count`      | number         | Number of results in this page.                                          |
| `nextCursor` | string \| null | Pass to `cursor` for the next page. `null` means you've reached the end. |

## Example: iterate companies

```bash theme={null}
# Page 1
GET /api/v1/companies?limit=50&search=acme

# Page 2
GET /api/v1/companies?limit=50&search=acme&cursor=cm_xyz
```

```typescript theme={null}
import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({ apiKey: process.env.ARCENPAY_API_KEY });

let cursor: string | undefined;
for (let i = 0; i < 20; i++) {
  const page = await client.listCompanies({ limit: 50, cursor });
  for (const company of page.data) {
    // process company
  }
  if (!page.nextCursor) break;
  cursor = page.nextCursor;
}
```

## Endpoints that paginate

| Endpoint                        | Notes                                                  |
| ------------------------------- | ------------------------------------------------------ |
| `GET /api/v1/companies`         | `limit`, `cursor`, `search`                            |
| `GET /api/v1/users`             | `limit`, `cursor`, `search`, `companyId`               |
| `GET /api/v1/checkout-sessions` | Returns the most recent 100 sessions; no cursor        |
| `GET /api/v1/events`            | `limit`, `eventType`, `companyId`                      |
| `GET /api/v1/proofs/zktls`      | `limit`, `companyId`, `providerId`                     |
| `GET /api/v1/audit-log`         | `limit` (1–200), `cursor`, filters (dashboard session) |
| Dashboard invoice/catalog lists | `limit`, `cursor` (dashboard session)                  |

<Note>
  When passing `cursor`, use the value exactly as returned. Values are opaque and may change between releases — never construct or mutate them yourself.
</Note>

## Related

* [Companies API](/api/companies) — full reference for the most common paginated resource
* [Users API](/api/users) — cursor pagination with `companyId` filter