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

# Search & Pagination

> Build precise buyer and signal queries with supported fields, dates, operators, and cursors.

Use `search_buyers` for people and company attributes. Use `search_signals` for activities, event dates, pages, UTM parameters, and click IDs.

Examples on this page are **tool arguments**, not REST request bodies. A custom agent sends them as the arguments of an MCP tool call. Some clients add a namespace to the tool name in their interface; the server names are `search_buyers` and `search_signals`.

## Choose the right timestamp

| Question | Tool and field |
| - | - |
| Which buyers were added during a period? | `search_buyers` → `created_at` |
| Which buyer records changed during a period? | `search_buyers` → `updated_at` |
| What activity happened during a period? | `search_signals` → `signal_at` |
| Which signal records were created during a period? | `search_signals` → `created_at` |

The `signal_at` filter maps to the signal's public `captured_at` timestamp. A signal can occur before its buyer or signal record is created. Filtering buyers by creation date and filtering signals by occurrence date can therefore return different sets of buyers.

For calendar periods, choose a time zone and convert its boundaries to RFC 3339 timestamps. Account for daylight saving time. Prefer a start-inclusive, end-exclusive range using `gte` and `lt`.

For example, October 19, 2026 in `America/Los_Angeles` runs from `2026-10-19T07:00:00Z` up to, but not including, `2026-10-20T07:00:00Z`:

```json theme={null}
{
  "filter": {
    "match": "all",
    "rules": [
      { "field": "signal_type", "operator": "eq", "value": "website" },
      { "field": "signal_at", "operator": "gte", "value": "2026-10-19T07:00:00Z" },
      { "field": "signal_at", "operator": "lt", "value": "2026-10-20T07:00:00Z" }
    ]
  },
  "limit": 25
}
```

These are illustrative dates. Replace them with the boundaries for your report.

## Rules and groups

A rule has `field`, `operator`, and `value`. Set a group's `match` to `all` for AND or `any` for OR. The default is `all`. The exposed input schema supports a top-level group containing rules and nested groups of rules.

This buyer search requires an ICP match and accepts either of two seniorities:

```json theme={null}
{
  "filter": {
    "match": "all",
    "rules": [
      { "field": "is_icp", "operator": "eq", "value": true },
      {
        "match": "any",
        "rules": [
          { "field": "seniority", "operator": "eq", "value": "founder" },
          { "field": "seniority", "operator": "eq", "value": "c_suite" }
        ]
      }
    ]
  },
  "limit": 10
}
```

`search_buyers` accepts an optional filter. `search_signals` requires a filter with at least one rule. Narrow large searches by date and relevant fields before retrieving pages.

## Operators and value formats

| Operator | Value | Meaning |
| - | - | - |
| `eq` | One value | Equal to the value. |
| `in` | Non-empty array | Match one of the values. |
| `not_in` | Non-empty array | Exclude the values; supported by specific buyer fields. |
| `contains` | One text value | Match text containing the value. |
| `starts_with` | One text value | Match a prefix; supported by specific signal URL fields. |
| `gt`, `gte`, `lt`, `lte` | One number or timestamp | Compare against a boundary. |
| `between` | `[low, high]` | Match a range. Use `gte` and `lt` when you need explicit calendar boundaries. |
| `in_last` | `{ "unit": "day", "value": 7 }` | Match a relative period. Units: `hour`, `day`, `week`, `month`. |

Use booleans for `has_*` and `is_*` fields. Dates must be RFC 3339 timestamps. Use each field only with the operators listed below.

For text such as industry, title, or company name, use the data's wording. `industry` and `company_location` equality and membership matches are case-insensitive. If the exact text is unknown, use `contains` where supported.

## Buyer filter reference

| Field | Operators | Scope |
| - | - | - |
| `annual_revenue` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `attribution_source` | `eq`, `in`, `not_in` | — |
| `attribution_type` | `eq`, `in`, `not_in` | — |
| `company_location` | `eq`, `in`, `contains` | — |
| `company_name` | `eq`, `in`, `contains` | — |
| `created_at` | `gt`, `gte`, `lt`, `lte`, `between`, `in_last` | — |
| `email` | `eq`, `in`, `contains` | — |
| `employee_count` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `founded_year` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `function` | `eq`, `in`, `contains` | — |
| `has_email` | `eq` | — |
| `has_linkedin` | `eq` | — |
| `has_phone` | `eq` | — |
| `has_verified_email` | `eq` | — |
| `has_verified_phone` | `eq` | — |
| `icp_id` | `eq`, `in` | — |
| `industry` | `eq`, `in`, `contains` | — |
| `is_icp` | `eq` | — |
| `is_persona` | `eq` | — |
| `linkedin_followers` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `linkedin_signal_count` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `location` | `eq`, `in` | — |
| `market_signal_count` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `name` | `contains` | — |
| `persona_id` | `eq`, `in` | — |
| `seniority` | `eq`, `in`, `contains` | — |
| `target_list_id` | `eq`, `in` | — |
| `title` | `eq`, `in`, `contains` | — |
| `total_funding` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `total_signal_count` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |
| `updated_at` | `gt`, `gte`, `lt`, `lte`, `between`, `in_last` | — |
| `website_signal_count` | `eq`, `gt`, `gte`, `lt`, `lte`, `between` | — |

### Enumerated buyer values

* `attribution_type`: `ai`, `direct`, `email`, `in_market`, `organic`, `paid`, `social`.
* `seniority`: `c_suite`, `director`, `entry`, `founder`, `head`, `intern`, `manager`, `owner`, `partner`, `senior`, `vp`.
* `attribution_source`: `bing`, `chatgpt`, `claude`, `competitor_intent`, `copilot`, `customer_marketing`, `direct`, `duckduckgo`, `facebook`, `gemini`, `google`, `google_ads`, `instagram`, `linkedin`, `linkedin_ads`, `linkedin_comment`, `linkedin_follow`, `linkedin_reaction`, `meta_ads`, `microsoft_ads`, `newsletter`, `nurture`, `other`, `outbound`, `perplexity`, `product_intent`, `quora_ads`, `reddit`, `reddit_ads`, `tiktok_ads`, `topic_intent`, `transactional`, `x`, `x_ads`, `yahoo`, `youtube`.

## Signal filter reference

| Field | Operators | Scope |
| - | - | - |
| `browser` | `eq`, `in` | Website only |
| `buyer_id` | `eq`, `in` | All signal types |
| `company_id` | `eq`, `in` | All signal types |
| `company_name` | `eq`, `in`, `contains` | All signal types |
| `created_at` | `gt`, `gte`, `lt`, `lte`, `between`, `in_last` | All signal types |
| `dclid` | `eq`, `contains` | Website only |
| `device_type` | `eq`, `in` | Website only |
| `fbclid` | `eq`, `contains` | Website only |
| `form_url` | `eq`, `in`, `contains`, `starts_with` | Website only |
| `gbraid` | `eq`, `contains` | Website only |
| `gclid` | `eq`, `contains` | Website only |
| `icp_id` | `eq`, `in` | All signal types |
| `li_fat_id` | `eq`, `contains` | Website only |
| `msclkid` | `eq`, `contains` | Website only |
| `operating_system` | `eq`, `in` | Website only |
| `persona_id` | `eq`, `in` | All signal types |
| `signal_at` | `gt`, `gte`, `lt`, `lte`, `between`, `in_last` | All signal types |
| `signal_type` | `eq`, `in` | All signal types |
| `target_page_id` | `eq`, `in` | Website only |
| `topic` | `eq`, `in`, `contains` | Market only |
| `trigger` | `eq`, `in` | All signal types |
| `ttclid` | `eq`, `contains` | Website only |
| `twclid` | `eq`, `contains` | Website only |
| `url` | `eq`, `in`, `contains`, `starts_with` | Website only |
| `utm_campaign` | `eq`, `contains` | Website only |
| `utm_content` | `eq`, `contains` | Website only |
| `utm_medium` | `eq`, `contains` | Website only |
| `utm_source` | `eq`, `contains` | Website only |
| `utm_term` | `eq`, `contains` | Website only |
| `wbraid` | `eq`, `contains` | Website only |

### Signal types and triggers

| `signal_type` | Compatible `trigger` values |
| - | - |
| `website` | `visited_page`, `filled_form`, `abandoned_form` |
| `market` | `researched_topic`, `explored_product`, `evaluated_competitor` |
| `linkedin` | `followed_page`, `followed_competitor`, `commented_post`, `reacted_post`, `authored_post` |

When you use a type-specific field or `trigger`, include a compatible `signal_type` rule in the **top-level** group and set that group's `match` to `all`. Putting the type rule only inside an OR subgroup does not satisfy this requirement.

For example, website form submissions in the last seven days:

```json theme={null}
{
  "filter": {
    "match": "all",
    "rules": [
      { "field": "signal_type", "operator": "eq", "value": "website" },
      { "field": "trigger", "operator": "eq", "value": "filled_form" },
      { "field": "signal_at", "operator": "in_last", "value": { "unit": "day", "value": 7 } }
    ]
  },
  "limit": 25
}
```

Signal search does not expose `attribution_type` or `attribution_source` as filters. For website activity attribution, retrieve the appropriate website signals and inspect `website.attribution`, `website.utm`, and `website.click_ids`. Buyer attribution is available as buyer search filters, but a buyer's attribution does not describe every later visit.

## Pagination and totals

Search and list payloads include `total`, `data`, and `next_cursor`. Search payloads also echo `applied_filter`. Clients may display the payload as parsed JSON or inside MCP content blocks.

The following example is illustrative:

```json theme={null}
{
  "total": 42,
  "data": [ { "id": "BUYER_ID" } ],
  "next_cursor": "OPAQUE_CURSOR"
}
```

1. Read `total` for the full matching count; it is not the current page length.
2. Use `data` for the current page.
3. If `next_cursor` is present, pass it unchanged as `cursor` with the same tool, filter, and sort order.
4. Stop when the server returns no continuation cursor.

Do not decode, edit, or reuse a cursor for another query. Search page sizes default to 25; list page sizes default to 100. Set a smaller `limit` when you need only a few examples. The tool schemas do not advertise a maximum page size.

For a count of **distinct buyers with activity**, a signal total is insufficient: several signals can reference one buyer. Retrieve the necessary signal pages, deduplicate `buyer_id`, and use `get_buyer` for the buyer details. For large ranges, narrow the scope; do not label the signal total as a unique-buyer count.

## Sorting and query size

Buyer and signal searches accept `sort_order`: `desc` for newest first (the default) or `asc` for oldest first. They do not expose a selectable `sort_by` field or an aggregation/ranking argument.

Do not claim a revenue ranking, a full source breakdown, or a unique-buyer total from one sample page. If the server returns `query_timeout`, narrow the dates or other conditions before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.