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

Search Website, Market, and LinkedIn Signals using structured filtering criteria with the 1eye API. Combine multiple conditions to find buying activities associated with specific companies, ICPs, Personas, website visits, market research, and LinkedIn engagement.

Search Signals enables developers, GTM platforms, and AI agents to discover relevant buying activity across all three Signal channels without retrieving and filtering entire datasets.

The API searches existing Signals and returns the same Signal objects available through the List Signals API.

**Search Signals is read-only.** Searches do not generate new Signals, trigger enrichment, reevaluate Buyers, or consume additional 1eye credits.

## Base URL

All Search Signals requests use:

```text theme={null}
https://api.1eye.ai/v1/signals/search
```

## Authentication

All requests require a valid 1eye API key.

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

API keys are scoped to a single workspace. Searches automatically return Signals belonging to the workspace associated with your API key.

You do not need to provide a workspace ID.

The examples below use `$API_KEY` as the environment variable containing your API key.

For more information, see [Authentication](/api-reference/auth).

## Endpoint

| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/v1/signals/search` | Search Signals using structured filtering criteria |

### Related Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/signals` | List Signals |
| `GET` | `/v1/signals/{signal_id}` | Retrieve a Signal |

Use **List Signals** for straightforward retrieval and **Search Signals** for advanced filtering using multiple conditions.

***

## 1. Search Request

Search Signals accepts a JSON request body containing structured filtering criteria.

The same request structure is used by Search Buyers.

### Example Request

Find Website Signals representing visits to Snowbricks' pricing page.

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/signals/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 100,
    "filter": {
      "match": "all",
      "rules": [
        {
          "field": "signal_type",
          "operator": "eq",
          "value": "website"
        },
        {
          "field": "trigger",
          "operator": "eq",
          "value": "visited_page"
        },
        {
          "field": "url",
          "operator": "contains",
          "value": "/pricing"
        }
      ]
    }
  }'
```

### Request Body

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "website"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "visited_page"
      },
      {
        "field": "url",
        "operator": "contains",
        "value": "/pricing"
      }
    ]
  }
}
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `limit` | integer | Maximum number of Signals returned |
| `filter` | object | Container for search conditions |
| `filter.match` | string | Logical operation used to combine rules |
| `filter.rules` | array | Array of filtering conditions |
| `field` | string | Signal attribute being filtered |
| `operator` | string | Comparison operation |
| `value` | varies | Value used for comparison |

### How Filtering Works

Each filter rule specifies:

1. **Field** – Which Signal attribute to search.
2. **Operator** – How the attribute should be compared.
3. **Value** – The value to compare against.

For example:

```json theme={null}
{
  "field": "signal_type",
  "operator": "eq",
  "value": "website"
}
```

Matches Website Signals.

Another example:

```json theme={null}
{
  "field": "url",
  "operator": "contains",
  "value": "/pricing"
}
```

Matches Signals whose searchable URL contains `/pricing`.

### Combining Multiple Rules

Use `filter.match` to control how conditions are combined.

| Value | Logic | Description |
| - | - | - |
| `all` | AND | Every rule must match |

For example:

```json theme={null}
{
  "match": "all",
  "rules": [
    {
      "field": "signal_type",
      "operator": "eq",
      "value": "website"
    },
    {
      "field": "url",
      "operator": "contains",
      "value": "/pricing"
    }
  ]
}
```

Returns Website Signals whose URLs contain `/pricing`.

The `all` operator is the standard matching mode for combining Signal Type with other search conditions.

### Result Limit

`limit` controls the maximum number of Signals returned in a response.

* Default: 100
* Maximum: 1,000
* Minimum: 1

The limit applies to the number of results returned, not the number of records evaluated.

***

## 2. Signal Type Filtering

1eye captures three types of buying Signals.

| Signal Type | Description | Example |
| - | - | - |
| `website` | Activity on your website | Visited a pricing page |
| `market` | External buying-intent activity | Researched lakehouse architecture |
| `linkedin` | Activity captured from LinkedIn | Followed a competitor's company page |

Search Signals supports searching one, multiple, or all three types.

**Signal Type is a standard filter inside `filter.rules`.** There is no separate `signal_types` request parameter.

### 2.1 Search Website Signals

Use `signal_type` with the `eq` operator.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "website"
      }
    ]
  }
}
```

Returns Website Signals only.

### 2.2 Search Market Signals

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "market"
      }
    ]
  }
}
```

Returns Market Signals only.

### 2.3 Search LinkedIn Signals

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "linkedin"
      }
    ]
  }
}
```

Returns LinkedIn Signals only.

### 2.4 Search Multiple Signal Types

Use the `in` operator to search multiple Signal types in one request.

For example, search Website and Market Signals:

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "in",
        "value": [
          "website",
          "market"
        ]
      }
    ]
  }
}
```

Returns matching Website and Market Signals.

LinkedIn Signals are excluded.

### 2.5 Search All Signal Types

To search across all three Signal types, omit the `signal_type` filter.

For example:

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "company_name",
        "operator": "contains",
        "value": "Acme Analytics"
      }
    ]
  }
}
```

Returns matching Website, Market, and LinkedIn Signals associated with Acme Analytics.

### Important

You do not need separate endpoints to search different Signal types.

The same endpoint supports every combination:

```text theme={null}
Website
Market
LinkedIn

Website + Market
Website + LinkedIn
Market + LinkedIn

Website + Market + LinkedIn
```

All results are returned through one unified Signal collection.

***

## 3. Signal Triggers

Every Signal represents an activity that has already occurred.

A Signal has two important attributes:

* `type` – Identifies the Signal channel.
* `trigger` – Identifies the activity that occurred.

For example:

```json theme={null}
{
  "type": "market",
  "trigger": "researched_topic"
}
```

Represents Market research activity.

### Supported Triggers

| Signal Type | Trigger | Description |
| - | - | - |
| Website | `visited_page` | Visited a webpage |
| Website | `filled_form` | Submitted a website form |
| Website | `abandoned_form` | Abandoned a website form |
| Market | `researched_topic` | Researched a market topic |
| Market | `explored_product` | Explored a product |
| Market | `evaluated_competitor` | Evaluated a competitor |
| LinkedIn | `followed_page` | Followed a LinkedIn company page |
| LinkedIn | `authored_post` | Authored a LinkedIn post |
| LinkedIn | `commented_post` | Commented on a LinkedIn post |
| LinkedIn | `reacted_post` | Reacted to a LinkedIn post |

### Trigger Filtering

Use the `trigger` field with `eq` or `in`.

For example:

```json theme={null}
{
  "field": "trigger",
  "operator": "eq",
  "value": "researched_topic"
}
```

Matches topic research activities.

### Trigger Validation

A trigger must be compatible with the selected Signal type.

For example:

**Valid:**

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "market"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "researched_topic"
      }
    ]
  }
}
```

**Invalid:**

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "website"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "researched_topic"
      }
    ]
  }
}
```

The second request is invalid because `researched_topic` is a Market trigger, not a Website trigger.

### Searching Multiple Triggers

Use the `in` operator.

For example, search Market Signals involving topic research or competitor evaluation:

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "market"
      },
      {
        "field": "trigger",
        "operator": "in",
        "value": [
          "researched_topic",
          "evaluated_competitor"
        ]
      }
    ]
  }
}
```

### Important

When filtering by `trigger`, include a compatible `signal_type` rule.

This ensures that trigger values are interpreted consistently across Website, Market, and LinkedIn Signals.

***

## 4. Common Signal Filters

Search Signals supports filtering by attributes shared across compatible Signal types.

These filters help identify activity associated with particular companies, Buyers, ICPs, Personas, and time periods.

### Common Filter Fields

| Field | Type | Supported Operators | Description |
| - | - | - | - |
| `signal_type` | enum | `eq`, `in` | Website, Market, or LinkedIn |
| `trigger` | enum | `eq`, `in` | Activity performed |
| `signal_at` | datetime | Datetime operators | Signal occurrence time |
| `created_at` | datetime | Datetime operators | Signal creation time |
| `company_id` | string | `eq`, `in` | Associated company ID |
| `company_name` | string | `eq`, `in`, `contains` | Associated company name |
| `icp_id` | string | `eq`, `in` | Associated ICP |
| `persona_id` | string | `eq`, `in` | Associated Persona |

A filter is available only when the corresponding attribute is supported by the selected Signal types.

### Example: Signals from an ICP

Find Website and Market Signals associated with Snowbricks' Cloud-Native SaaS ICP.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "in",
        "value": [
          "website",
          "market"
        ]
      },
      {
        "field": "icp_id",
        "operator": "eq",
        "value": "icp_363250364328685568"
      }
    ]
  }
}
```

Returns matching Website and Market Signals associated with the specified ICP.

### Example: Signals from a Company

Find buying activity associated with Acme Analytics, a fictional prospective Snowbricks customer.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "company_name",
        "operator": "contains",
        "value": "Acme Analytics"
      }
    ]
  }
}
```

Because no Signal Type is specified, the search includes all three channels.

***

## 5. Website Signal Filters

Website Signals represent activity captured on your website.

Examples include page visits, form submissions, and abandoned forms.

Search Website Signals using URL, page, form, device, browser, and attribution criteria.

### Website Filter Fields

| Field | Type | Supported Operators | Description |
| - | - | - | - |
| `url` | string | `eq`, `in`, `contains`, `starts_with` | Visited page URL |
| `form_url` | string | `eq`, `in`, `contains`, `starts_with` | Form URL |
| `target_page_id` | string | `eq`, `in` | Associated Target Page |
| `browser` | string | `eq`, `in` | Browser |
| `device_type` | enum | `eq`, `in` | Device type |
| `operating_system` | string | `eq`, `in` | Operating system |
| `utm_source` | string | `eq`, `contains` | UTM source |
| `utm_medium` | string | `eq`, `contains` | UTM medium |
| `utm_campaign` | string | `eq`, `contains` | UTM campaign |
| `utm_content` | string | `eq`, `contains` | UTM content |
| `utm_term` | string | `eq`, `contains` | UTM term |

### Device Types

Supported values:

```text theme={null}
desktop
mobile
tablet
```

### Example: Pricing Page Visits

Find visitors who viewed Snowbricks' pricing page.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "website"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "visited_page"
      },
      {
        "field": "url",
        "operator": "contains",
        "value": "snowbricks.io/pricing"
      }
    ]
  }
}
```

### Example: Demo Form Submissions

Find Website Signals representing form submissions on Snowbricks' demo page.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "website"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "filled_form"
      },
      {
        "field": "form_url",
        "operator": "contains",
        "value": "snowbricks.io/demo"
      }
    ]
  }
}
```

### Example: Visitors from Google Ads

Find Website Signals attributed to Google Ads campaigns using UTM tracking.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "website"
      },
      {
        "field": "utm_source",
        "operator": "eq",
        "value": "google"
      }
    ]
  }
}
```

### URL Matching

Website Signal Search supports several URL comparison operators:

* `eq` – Match an exact URL value.
* `in` – Match any URL in a supplied set.
* `contains` – Match URLs containing specified text.
* `starts_with` – Match URLs beginning with specified text.

These are search operators for existing Signal records.

They are separate from Knowledge Base Target Page and Target Form configuration, which uses canonical URL matching.

### Important

Website-specific filters should be combined with:

```json theme={null}
{
  "field": "signal_type",
  "operator": "eq",
  "value": "website"
}
```

This ensures the search is restricted to compatible Signals.

***

## 6. Market Signal Filters

Market Signals capture external buying-intent activity related to relevant topics, products, and competitors.

For example, Snowbricks might identify potential customers researching lakehouse architecture, cloud data warehousing, or competing data platforms.

### Market Triggers

| Trigger | Description |
| - | - |
| `researched_topic` | Researched a relevant market topic |
| `explored_product` | Explored a product |
| `evaluated_competitor` | Evaluated a competitor |

### Market Filter Fields

| Field | Type | Supported Operators | Description |
| - | - | - | - |
| `signal_type` | enum | `eq`, `in` | Signal category |
| `trigger` | enum | `eq`, `in` | Market activity |
| `topic` | string | `eq`, `in`, `contains` | Market topic |
| `signal_at` | datetime | Datetime operators | Activity timestamp |

Common company, ICP, and Persona filters may also be combined with Market-specific filters where supported.

### Example: Lakehouse Research

Find Market Signals involving research into lakehouse architecture.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "market"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "researched_topic"
      },
      {
        "field": "topic",
        "operator": "contains",
        "value": "lakehouse"
      }
    ]
  }
}
```

### Example: Competitor Evaluations

Find Market Signals where potential Buyers evaluated competitors.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "market"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "evaluated_competitor"
      }
    ]
  }
}
```

### How Market Signal Search Works

Search operates on Market Signals already captured by 1eye.

It does not:

* Initiate new market research.
* Generate additional intent data.
* Enrich new Buyers.
* Create historical Market Signals.

**Searching existing Market Signals consumes no additional 1eye credits.**

***

## 7. LinkedIn Signal Filters

LinkedIn Signals represent activity captured from LinkedIn, including company-page follows and post engagement.

These Signals can help identify people engaging with companies and conversations relevant to your business.

### LinkedIn Triggers

| Trigger | Description |
| - | - |
| `followed_page` | Followed a company page |
| `authored_post` | Authored a post |
| `commented_post` | Commented on a post |
| `reacted_post` | Reacted to a post |

### LinkedIn Filter Fields

| Field | Type | Supported Operators | Description |
| - | - | - | - |
| `signal_type` | enum | `eq`, `in` | Signal category |
| `trigger` | enum | `eq`, `in` | LinkedIn activity |
| `signal_at` | datetime | Datetime operators | Activity timestamp |

Common company, ICP, and Persona filters may also be combined with LinkedIn filters where supported.

### Example: Followed Company Pages

Find LinkedIn Signals representing company-page follows.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "linkedin"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "followed_page"
      }
    ]
  }
}
```

### Example: LinkedIn Post Engagement

Find LinkedIn Signals representing reactions or comments on posts.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        {
          "field": "signal_type",
          "operator": "eq",
          "value": "linkedin"
        },
        {
          "field": "trigger",
          "operator": "in",
          "value": [
            "commented_post",
            "reacted_post"
          ]
        }
      }
    ]
  }
}
```

### Important

LinkedIn Signal Search operates only on activity already available in 1eye.

It does not perform live LinkedIn searches, discover new followers, or generate additional LinkedIn Signals.

***

## 8. Cross-Channel Signal Search

One of the key capabilities of Search Signals is the ability to search multiple buying-intent channels in a single request.

For example, Snowbricks might want to identify recent Website and Market Signals from companies matching its ideal customer profile.

### Example: Website + Market Signals

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "in",
        "value": [
          "website",
          "market"
        ]
      },
      {
        "field": "icp_id",
        "operator": "eq",
        "value": "icp_363250364328685568"
      }
    ]
  }
}
```

### Example: Multiple Signal Types and Triggers

Find Website page visits and Market topic research activity.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "in",
        "value": [
          "website",
          "market"
        ]
      },
      {
        "field": "trigger",
        "operator": "in",
        "value": [
          "visited_page",
          "researched_topic"
        ]
      }
    ]
  }
}
```

This request searches both selected Signal types.

### Filter Compatibility

When multiple Signal types are selected:

* Shared filters can be applied across all selected types.
* Type-specific filters must be compatible with every selected type.
* Trigger values must belong to the selected Signal types.
* Incompatible filter combinations return validation errors.

For example, selecting LinkedIn Signals while filtering by Website UTM parameters is invalid.

### Global Results

Cross-channel searches return one combined Signal collection.

Results are globally sorted by Signal occurrence time.

For example:

| Captured At | Signal Type | Activity |
| - | - | - |
| 10:05 AM | Website | Visited pricing page |
| 10:02 AM | LinkedIn | Followed company page |
| 9:58 AM | Market | Researched lakehouse architecture |
| 9:54 AM | Website | Submitted demo form |
| 9:49 AM | Market | Evaluated competitor |

Results are not grouped into separate Website, Market, and LinkedIn collections.

***

## 9. Search Operators

Search Signals supports structured comparisons using field-specific operators.

| Operator | Description | Example |
| - | - | - |
| `eq` | Equals | Signal type equals Website |
| `in` | Matches any value in a set | Website or Market Signals |
| `not_in` | Excludes specified values | Exclude selected attribution sources |
| `contains` | Contains text | URL contains `/pricing` |
| `starts_with` | Begins with text | URL starts with a specified prefix |
| `gt` | Greater than | Duration greater than a specified value |
| `gte` | Greater than or equal | Captured at or after a timestamp |
| `lt` | Less than | Duration below a specified value |
| `lte` | Less than or equal | Captured at or before a timestamp |
| `between` | Within a range | Value between two boundaries |
| `in_last` | Within a recent period | Signals captured during a recent period |

### Field-Specific Validation

Not every operator is supported by every field.

For example:

* `signal_type` supports `eq` and `in`.
* `trigger` supports `eq` and `in`.
* `url` supports `eq`, `in`, `contains`, and `starts_with`.
* `signal_at` supports datetime operators.
* `company_name` supports string comparisons.

Unsupported field/operator combinations return validation errors.

### Value Types

Values must match the field's expected type.

**String**

```json theme={null}
{
  "field": "company_name",
  "operator": "contains",
  "value": "Analytics"
}
```

**Enum**

```json theme={null}
{
  "field": "signal_type",
  "operator": "eq",
  "value": "market"
}
```

**Array**

```json theme={null}
{
  "field": "signal_type",
  "operator": "in",
  "value": [
    "website",
    "market"
  ]
}
```

**Datetime**

```json theme={null}
{
  "field": "signal_at",
  "operator": "gte",
  "value": "2026-10-01T00:00:00Z"
}
```

Invalid value types return `400 Bad Request`.

***

## 10. Timestamp Filters

Search Signals supports filtering by Signal occurrence time and creation time.

| Field | Type | Description |
| - | - | - |
| `signal_at` | datetime | When the Signal occurred |
| `created_at` | datetime | When the Signal record was created in 1eye |

### Signal Occurrence Time

Use `signal_at` when searching buying activities during a specific time period.

The filter maps to the Signal's public `captured_at` timestamp.

### Example: Recent Buying Activity

Find Signals captured on or after October 1, 2026.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_at",
        "operator": "gte",
        "value": "2026-10-01T00:00:00Z"
      }
    ]
  }
}
```

This searches across all three Signal types.

### Datetime Operators

| Operator | Description |
| - | - |
| `gt` | After |
| `gte` | At or after |
| `lt` | Before |
| `lte` | At or before |
| `between` | Within a specified range |
| `in_last` | Within a recent time period |

Timestamps use UTC in ISO 8601 format.

***

## 11. Response Structure

Search Signals returns the same Signal objects as the existing List Signals API.

There is no separate Search Signal response model.

### Example Response

**200 OK**

The following abbreviated example illustrates a response containing multiple Signal types.

```json theme={null}
{
  "data": [
    {
      "id": "sig_123456789012345678",
      "type": "website",
      "trigger": "visited_page",
      "captured_at": "2026-10-18T18:05:00Z"
    },
    {
      "id": "sig_123456789012345679",
      "type": "market",
      "trigger": "researched_topic",
      "captured_at": "2026-10-18T18:02:00Z"
    },
    {
      "id": "sig_123456789012345680",
      "type": "linkedin",
      "trigger": "followed_page",
      "captured_at": "2026-10-18T17:58:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

The example is abbreviated for readability. Actual responses include the full Signal object, including shared and type-specific properties.

### Response Fields

Search Signals preserves the existing Signal object, including:

* Signal identifier.
* Signal type.
* Signal trigger.
* Associated Buyer and company information, where available.
* Signal occurrence timestamp.
* Website-specific information.
* Market-specific information.
* LinkedIn-specific information.
* Applicable system-generated metadata.

The object matching the Signal type contains the relevant type-specific data.

Other type-specific objects remain `null`, consistent with the existing Signal API.

For complete Signal object definitions, see [Retrieve a Signal](/api-reference/retrieve-a-signal).

### Empty Results

If no Signals match the search, the API returns:

**200 OK**

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

No matching Signals is not considered an error.

***

## 12. Pagination & Sorting

Search Signals uses cursor-based pagination, consistent with the existing 1eye Public API.

### Pagination

* Default page size: 100.
* Maximum page size: 1,000.
* Results are returned in pages.
* Each response includes `pagination.next_cursor`.
* A `null` next cursor indicates the end of the result set.

Continuation requests must preserve the original search conditions and sorting.

Cursors are opaque and must not be modified or reused with different searches.

See [Pagination](/api-reference/pagination).

### Sorting

Search results follow the existing public Signal sorting conventions.

**Default ordering:**

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

The Signal ID acts as a deterministic tie-breaker when multiple Signals share the same capture timestamp.

### Cross-Type Sorting

When searching multiple Signal types, results are sorted globally.

For example:

```text theme={null}
10:05 – Website
10:02 – LinkedIn
09:58 – Market
09:54 – Website
09:49 – LinkedIn
```

The API does not paginate Website, Market, and LinkedIn Signals independently.

**One search returns one globally ordered collection with one continuation cursor.**

See [Filtering & Sorting](/api-reference/filtering-and-sorting).

***

## 13. Search Signals vs. Search Buyers

Search Signals and Search Buyers serve different purposes.

| API | Purpose |
| - | - |
| Search Signals | Find individual buying activities |
| Search Buyers | Find Buyers matching specific characteristics |

### Search Signals

Searches existing Signal records using attributes such as:

* Signal type.
* Activity trigger.
* Website URL.
* Form URL.
* Market topic.
* LinkedIn activity.
* Company or ICP association.
* Signal timestamp.

### Search Buyers

Searches existing Buyer Intelligence using attributes such as:

* Contact information.
* Company characteristics.
* ICP and Persona matches.
* Target List memberships.
* Aggregated Signal Counts.
* Attribution.

### Example

**Question:** Find Website Signals involving visits to Snowbricks' pricing page.

Use Search Signals:

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "website"
      },
      {
        "field": "url",
        "operator": "contains",
        "value": "snowbricks.io/pricing"
      }
    ]
  }
}
```

**Question:** Find Buyers who have generated at least three Website Signals.

Use Search Buyers with:

```json theme={null}
{
  "field": "website_signal_count",
  "operator": "gte",
  "value": 3
}
```

Search Signals finds individual events.

Search Buyers finds the people and companies behind accumulated buying activity.

***

## 14. Filter Validation

Search Signals validates every supplied filter against the selected Signal types.

### Requirements

* Fields must be supported by Signal Search.
* Operators must be valid for the selected field.
* Values must use the expected type.
* Enum values must be recognized.
* Trigger values must be compatible with the selected Signal types.
* Type-specific filters must be compatible with every selected Signal type.
* Unsupported conditions must not be silently ignored.

### Invalid Signal Type

For example:

```json theme={null}
{
  "field": "signal_type",
  "operator": "eq",
  "value": "instagram"
}
```

Returns a validation error because `instagram` is not a supported Signal type.

### Invalid Trigger Combination

For example:

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "linkedin"
      },
      {
        "field": "trigger",
        "operator": "eq",
        "value": "researched_topic"
      }
    ]
  }
}
```

Returns a validation error because `researched_topic` is a Market trigger.

### Incompatible Filter

For example:

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "signal_type",
        "operator": "eq",
        "value": "linkedin"
      },
      {
        "field": "utm_source",
        "operator": "eq",
        "value": "google"
      }
    ]
  }
}
```

Returns a validation error because `utm_source` is a Website-specific attribute.

### Missing Values

When a Signal lacks a particular attribute:

* Missing fields do not satisfy positive comparisons.
* Null values are not interpreted as zero.
* Unsupported fields are not silently ignored.

**Invalid queries return errors rather than misleading search results.**

***

## 15. Error Handling

Search Signals uses the standard 1eye API error format.

| HTTP Status | Description |
| - | - |
| `200` | Search completed successfully |
| `400` | Invalid request or filter |
| `401` | Invalid or missing API key |
| `403` | Insufficient permissions |
| `429` | Workspace rate limit exceeded |
| `500` | Internal server error |

### Invalid Filter

Unsupported filters or incompatible Signal-type combinations return `400 Bad Request`.

### Example Error

**400 Bad Request**

```json theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "The filter 'utm_source' is not supported for LinkedIn Signals.",
    "param": "filter.rules",
    "request_id": "req_359051753366339585"
  }
}
```

### Common Validation Errors

* Unsupported Signal type.
* Unsupported trigger.
* Invalid Signal type/trigger combination.
* Unknown filter field.
* Unsupported operator.
* Invalid value type.
* Invalid enum value.
* Missing or malformed filter rules.
* Invalid result limit.
* Invalid pagination cursor.
* Incompatible type-specific filters.

The API does not silently ignore unsupported search conditions.

For more information, see [Errors](/api-reference/errors).

***

## 16. Rate Limits & Credits

### Rate Limits

Search Signals requests count toward your workspace API rate limits.

Rate limits are shared across all API keys belonging to the same workspace.

If a workspace exceeds its rate limit, the API returns:

**429 Too Many Requests**

Follow the `Retry-After` header when provided.

See [Rate Limits](/api-reference/rate-limits).

### Credits

**Search Signals does not consume additional 1eye credits.**

The API searches existing Signal Intelligence already available in your workspace.

It does not:

* Generate new Website Signals.
* Generate new Market Signals.
* Generate new LinkedIn Signals.
* Resolve new Buyers.
* Enrich contacts or companies.
* Trigger REEM evaluations.
* Perform live LinkedIn or Market research.
* Recalculate historical buying activity.
* Initiate Destination workflows.

Search operations are read-only.

***

## 17. Best Practices

### Always Specify Signal Type for Channel-Specific Searches

When searching for Website, Market, or LinkedIn-specific attributes, include an explicit `signal_type` filter.

This improves clarity and ensures your filters apply to compatible Signals.

### Use Triggers to Find Meaningful Activities

Combine Signal Type and Trigger to search for specific activities.

Examples:

* Website + `visited_page`
* Website + `filled_form`
* Market + `researched_topic`
* Market + `evaluated_competitor`
* LinkedIn + `followed_page`
* LinkedIn + `commented_post`

### Use Cross-Channel Searches for Broader Intelligence

Omit `signal_type` when searching for activity across all three channels using shared filters.

For example, search all activity associated with a specific company or ICP.

### Combine Filters to Narrow Results

Use `match: "all"` to combine Signal Type, Trigger, Company, ICP, and time conditions.

This helps reduce irrelevant results and identify specific buying activities.

### Use Time Filters for Recency

Recent buying activity is often more actionable than older activity.

Use `signal_at` to search for Signals captured during a relevant time period.

### Use Website URLs for Page-Level Intent

Search pricing, demo, product, and integration page visits to identify direct engagement with your website.

### Use Market Topics for Research Intent

Market Signals can reveal interest in broader technologies and business challenges, even when a Buyer has not visited your website.

### Use LinkedIn Signals for Social Buying Activity

LinkedIn Signals can provide additional context when potential Buyers engage with relevant company pages or posts.

### Use Pagination for Large Result Sets

Use cursor pagination rather than requesting unnecessarily large result sets.

### Use Search Buyers for Buyer-Level Filtering

When your goal is to find people or companies matching ICPs, Personas, firmographics, or accumulated Signal Counts, use Search Buyers.

Use Search Signals when your criteria relate to individual buying activities.

***

## 18. Related Documentation

* [Authentication](/api-reference/auth)
* [Filtering & Sorting](/api-reference/filtering-and-sorting)
* [Pagination](/api-reference/pagination)
* [Errors](/api-reference/errors)
* [Rate Limits](/api-reference/rate-limits)
* [List Signals](/api-reference/list-signals)
* [Retrieve a Signal](/api-reference/retrieve-a-signal)
* [List Buyers](/api-reference/list-buyers)
* [Knowledge Base – ICPs](/knowledge-base/icps)
* [Knowledge Base – Topics](/topics)
* [Knowledge Base – Competitors](/competitors)


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