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

# Pagination

> Paginate through large result sets using cursor-based pagination.

The 1eye API uses **cursor-based pagination** for collection endpoints.

Offset-based pagination is not supported.

## Page size

Use the `limit` parameter to control the number of records returned in a request.

Default:

```text theme={null}
limit=100
```

Maximum:

```text theme={null}
limit=1000
```

Example:

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?limit=100" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

## Response

Collection responses include a `pagination` object containing `next_cursor`.

```text theme={null}
{
  "data": [
    {
      "id": "buy_340192783061721088"
    },
    {
      "id": "buy_338667580758585344"
    }
  ],
  "pagination": {
    "next_cursor": "eyJ..."
  }
}
```

If `next_cursor` contains a value, additional results are available.

## Retrieve the next page

Pass the returned `next_cursor` value using the `cursor` parameter.

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?limit=100&cursor=eyJ..." \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

Continue requesting pages until `next_cursor` is `null`.

```text theme={null}
{
  "data": [],
  "pagination": {
    "next_cursor": null
  }
}
```

## Signals

Pagination works the same way for Signals.

First request:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?limit=100" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

Next request:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?limit=100&cursor=eyJ..." \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

## When to stop

Always stop pagination only when:

```text theme={null}
{
  "next_cursor": null
}
```

Do not determine whether additional pages exist based on the number of records returned.

For example, a page containing fewer records than the requested `limit` does not necessarily mean it is the final page.

The API does not return a total result count in v1.

## Cursor behavior

Cursors are generated by 1eye and should be treated as opaque values.

Do not:

* Construct cursors yourself
* Modify a cursor
* Decode a cursor
* Reuse a cursor with a different endpoint

A cursor is tied to the endpoint, filters, and sorting used to create it.

For example, a cursor returned by:

```text theme={null}
GET /v1/buyers
```

cannot be used with:

```text theme={null}
GET /v1/signals
```

## Keep filters and sorting consistent

When using a cursor to retrieve the next page, the following must remain unchanged:

* Endpoint
* Filters
* `sort_by`
* `sort_order`

For example, if the first request is:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?type=website&sort_by=captured_at&sort_order=desc&limit=100" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

the next request must use the same filters and sorting:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?type=website&sort_by=captured_at&sort_order=desc&limit=100&cursor=eyJ..." \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

## Changing the page size

The `limit` may change between pages.

For example:

```text theme={null}
Page 1: limit=100
Page 2: limit=50
```

This is valid as long as the endpoint, filters, and sorting remain unchanged.

## Invalid cursors

A malformed, modified, or mismatched cursor returns:

```text theme={null}
400 Bad Request
```

with the error code:

```text theme={null}
invalid_cursor
```