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

# Discovery Watchers

> Turn any person or company search into a recurring feed. A Discovery Watcher re-runs your filters on a schedule and pushes new matches to a webhook, Slack, or email.

A **Discovery Watcher** is a saved Person or Company search that runs on a schedule. Each run re-evaluates your filters against Crustdata's database and pushes any new matches to your delivery channel — a webhook, Slack, or email. Instead of re-running a search yourself, you get a continuous, deduplicated feed of **new** people or companies that match your criteria.

Common uses:

* **Recruiting** — a fresh feed of candidates matching a role (e.g. *ML engineers in Paris who previously worked at a top AI lab*).
* **Sales / GTM** — new decision-makers entering your ICP.
* **Market intelligence** — companies that newly match a segment (e.g. *Brazilian fintechs that crossed 30% headcount growth*).

There are two create endpoints, one per dataset:

**Watch for people:**

```
POST https://api.crustdata.com/watch/person/search
```

**Watch for companies:**

```
POST https://api.crustdata.com/watch/company/search
```

<Note>
  Every request requires the `x-api-version: 2025-11-01` header and a Bearer
  token. Replace `YOUR_API_KEY` in each example with your API key.
</Note>

<Callout icon="coins" color="#5345e4">
  <strong>Pricing:</strong> the first run is a <strong>free baseline</strong> (a
  sample of up to 5 matches). After that you're charged only for records
  delivered — <code>0.5 credits per new person</code> or
  <code>2 credits per new company</code>. See
  [Person pricing](/watcher-docs/discovery/person#pricing) and
  [Company pricing](/watcher-docs/discovery/company#pricing).
</Callout>

## How a watcher runs

<Steps>
  <Step title="Create the watch">
    `POST` your `filters`, a `config` (schedule + result cap), and one or more
    `notifications` channels. The response returns a watch `id`.
  </Step>

  <Step title="Baseline run (free)">
    Within seconds, the watcher does its first run and delivers a
    **free baseline sample of up to 5 matches** so you can confirm the setup and
    payload shape. No credits are charged.
  </Step>

  <Step title="Recurring runs">
    On the schedule you set (`every_hours`), the watcher re-runs your filters and
    delivers records that are **new or refreshed since the previous run**, up to
    `max_results_per_run`. You're charged per delivered record.
  </Step>
</Steps>

<Note>
  Each run delivers matches whose profile was **added or updated since the last
  run** — so a watcher is a feed of *movement* within your filter set, not a
  one-time export. To pull the full current set of matches instead, use
  [Person Search](/person-docs/search/introduction) or
  [Company Search](/company-docs/search/introduction).
</Note>

## Filters

Watcher filters use the **exact same syntax and fields** as the search APIs — the
`{ "op": "and" | "or", "conditions": [...] }` tree with `field` / `type` / `value`
leaves. You don't need to learn a new filter language:

* Person watchers → [Person Search reference](/person-docs/search/reference)
* Company watchers → [Company Search reference](/company-docs/search/reference)

## Delivery channels

Every watch needs at least one channel in `notifications`. You can add several and
matches fan out to all of them.

| Channel | Shape                                                                      |
| ------- | -------------------------------------------------------------------------- |
| Webhook | `{ "type": "webhook", "url": "https://…", "headers": { … } }`              |
| Slack   | `{ "type": "slack", "webhook_url": "https://hooks.slack.com/services/…" }` |
| Email   | `{ "type": "email", "to": ["you@company.com"] }`                           |

<Warning>
  A Slack channel must be a real **Slack incoming webhook**
  (`https://hooks.slack.com/services/…`). Pasting any other URL will fail
  delivery.
</Warning>

## Quick start

Create a person watcher that alerts a webhook daily when new heads of data at
mid-size US companies appear:

<CodeGroup>
  ```bash Request theme={"theme":"vitesse-black"}
  curl --request POST \
    --url https://api.crustdata.com/watch/person/search \
    --header 'authorization: Bearer YOUR_API_KEY' \
    --header 'content-type: application/json' \
    --header 'x-api-version: 2025-11-01' \
    --data '{
      "filters": {
        "op": "and",
        "conditions": [
          { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Head of Data" },
          { "field": "professional_network.location.raw", "type": "(.)", "value": "United States" }
        ]
      },
      "config": {
        "trigger": { "type": "interval", "every_hours": 24 },
        "max_results_per_run": 25
      },
      "notifications": [
        { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" }
      ]
    }'
  ```

  ```json Response theme={"theme":"vitesse-black"}
  { "id": 46849 }
  ```
</CodeGroup>

<CardGroup cols={3}>
  <Card title="Person watchers" icon="user" href="/watcher-docs/discovery/person">
    Watch for people — recipes, delivery options, and pricing.
  </Card>

  <Card title="Company watchers" icon="building" href="/watcher-docs/discovery/company">
    Watch for companies — segment, growth, and funding recipes.
  </Card>

  <Card title="Entity watchers" icon="clock" href="/watcher-docs/entity/introduction">
    Watch a known list for profile changes. Coming soon.
  </Card>
</CardGroup>