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

# Pagination

> Navigate large result sets with offset-based pagination

# Pagination

List endpoints in the Operate API return paginated results. Use the `limit` and `offset` query parameters to control which slice of data you receive.

## Parameters

| Parameter | Type   | Default | Range | Description                                      |
| --------- | ------ | ------- | ----- | ------------------------------------------------ |
| `limit`   | number | `50`    | 1–100 | Maximum number of items to return per page       |
| `offset`  | number | `0`     | 0+    | Number of items to skip before returning results |

## Example

Fetch the second page of 25 companies:

```bash theme={null}
curl -X GET "https://api.operate.so/companies/list?limit=25&offset=25" \
  -H "x-api-key: your-api-key-here"
```

## Response shape

Every paginated response includes a `pagination` object alongside the data:

```json theme={null}
{
  "success": true,
  "data": {
    "companies": [...],
    "pagination": {
      "total": 73,
      "limit": 25,
      "offset": 25
    }
  }
}
```

| Field    | Description                              |
| -------- | ---------------------------------------- |
| `total`  | Total number of items matching the query |
| `limit`  | The limit that was applied               |
| `offset` | The offset that was applied              |

## Iterating through all pages

To fetch all items, increment `offset` by `limit` until you've retrieved `total` items:

```javascript theme={null}
let offset = 0;
const limit = 50;
let allCompanies = [];

while (true) {
  const response = await fetch(
    `https://api.operate.so/companies/list?limit=${limit}&offset=${offset}`,
    { headers: { "x-api-key": apiKey } },
  );

  const { data } = await response.json();
  allCompanies.push(...data.companies);

  if (allCompanies.length >= data.pagination.total) break;
  offset += limit;
}
```

<Tip>
  Keep `limit` at 50 or below for optimal performance. The maximum allowed value
  is 100.
</Tip>