> ## 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.

# Filtering & Sorting

> Filter API results and control the order in which records are returned.

The 1eye API supports filtering and sorting on collection endpoints using query parameters.

When multiple filters are included in a request, they are combined using `AND`.

## Filter Buyers

Use the following filters with `GET /v1/buyers`:

| Parameter        | Description                                      |
| :--------------- | :----------------------------------------------- |
| `created_after`  | Return Buyers created at or after this timestamp |
| `created_before` | Return Buyers created before this timestamp      |

Example:

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?created_after=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

## Filter Signals

Use the following filters with `GET /v1/signals`:

| Parameter         | Description                                        |
| :---------------- | :------------------------------------------------- |
| `buyer_id`        | Return Signals associated with a specific Buyer    |
| `type`            | Filter by Signal type                              |
| `trigger`         | Filter by Signal trigger                           |
| `captured_after`  | Return Signals captured at or after this timestamp |
| `captured_before` | Return Signals captured before this timestamp      |

### Signal types and triggers

| Type       | Supported triggers                                             |
| :--------- | :------------------------------------------------------------- |
| `website`  | `visited_page`, `filled_form`, `abandoned_form`                |
| `market`   | `researched_topic`, `explored_product`, `evaluated_competitor` |
| `linkedin` | `followed_page`, `commented_post`, `reacted_post`              |

If `trigger` is provided, `type` is required.

Example:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?type=website&trigger=visited_page" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

Example — Market Signals:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?type=market&trigger=evaluated_competitor" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

Example — Signals for a specific Buyer:

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

## Combine filters

Multiple filters are combined using `AND`.

Example:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?buyer_id=buy_340192783061721088&type=website&trigger=visited_page" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

This means:

```text theme={null}
buyer_id = buy_340192783061721088
AND
type = website
AND
trigger = visited_page
```

Complex Boolean filtering is not supported in v1.

## Filter by time

Time filters use inclusive-start and exclusive-end semantics.

```text theme={null}
created_after   >=
created_before  <

captured_after  >=
captured_before <
```

Example:

```text theme={null}
curl "https://api.1eye.ai/v1/signals?captured_after=2026-09-17T00:00:00Z&captured_before=2026-09-18T00:00:00Z" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

This means:

```text theme={null}
captured_at >= 2026-09-17T00:00:00Z
AND
captured_at < 2026-09-18T00:00:00Z
```

All timestamps use UTC in the following format:

```text theme={null}
YYYY-MM-DDTHH:mm:ssZ
```

For Signals, customer-facing event-time filtering uses `captured_at`, which represents when the Signal occurred.

## Sort results

Collection endpoints support:

* `sort_by`
* `sort_order`

Supported `sort_order` values are:

```text theme={null}
asc
desc
```

### Buyers

GET buyers only support `created_at`

Example:

```text theme={null}
curl "https://api.1eye.ai/v1/buyers?sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"
```

### Signals

GET signals only supports `captured_at`

Example:

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

## Default sorting

Buyers are sorted by default using:

```text theme={null}
created_at DESC
id DESC
```

Signals are sorted by default using:

```text theme={null}
captured_at DESC
id DESC
```

The resource ID is automatically used as a deterministic tie-breaker.

Clients do not need to specify the ID in `sort_by`.

## Invalid parameters

The API does not silently ignore invalid query input.

Unknown query parameters, invalid filter values, unsupported sort fields, invalid sort directions, and invalid `type` / `trigger` combinations return:

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

Example:

```text theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown query parameter: emial.",
    "param": "emial",
    "request_id": "req_359051753366339585"
  }
}
```