1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

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:

limit=100

Maximum:

limit=1000

Example:

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.

{
  "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.

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.

{
  "data": [],
  "pagination": {
    "next_cursor": null
  }
}

Signals

Pagination works the same way for Signals. First request:

curl "https://api.1eye.ai/v1/signals?limit=100" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Next request:

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:

{
  "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:

GET /v1/buyers

cannot be used with:

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:

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:

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:

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:

400 Bad Request

with the error code:

invalid_cursor

Get Started

Buyers

Signals

Pagination

Page size

Response

Retrieve the next page

Signals

When to stop

Cursor behavior

Keep filters and sorting consistent

Changing the page size

Invalid cursors

​Page size

​Response

​Retrieve the next page

​Signals

​When to stop

​Cursor behavior

​Keep filters and sorting consistent

​Changing the page size

​Invalid cursors

Page size

Response

Retrieve the next page

Signals

When to stop

Cursor behavior

Keep filters and sorting consistent

Changing the page size

Invalid cursors