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

# Company Discovery Watcher

> Turn a company search into a recurring feed. A Company Discovery Watcher re-runs your filters on a schedule and pushes new matching companies to a webhook or Slack.

A **Company Discovery Watcher** turns a [Company Search](/company-docs/search/introduction) filter into a recurring feed. Each run re-evaluates your filters against Crustdata's database and delivers only the **new** matches to a webhook or Slack — a continuous, deduplicated feed, with no manual re-running.

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

<Callout icon="coins" color="#5345e4">
  <strong>Pricing:</strong> the first run is a free baseline (a sample of up to 5
  matches), then <code>2 credits per new company</code> delivered.
</Callout>

Common uses:

* **Sales / GTM** — new accounts entering your ICP (e.g. *Brazilian fintechs that crossed 30% headcount growth*).
* **Market intelligence** — companies that newly match a segment, funding stage, or growth band.
* **Sourcing** — a fresh pipeline of recently founded or fast-growing companies in your target market.

<Note>
  A Discovery Watcher tracks companies that **newly match a filter**. To watch a
  **known list** of companies for profile changes instead, use the
  [Company Entity Watcher](/watcher-docs/company/entity).
</Note>

## 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)">
    The first run happens within seconds, delivering a **free baseline sample of
    up to 5 matches** so you can confirm the setup and payload shape. No credits
    charged.
  </Step>

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

<Note>
  Each run delivers companies **added or updated since the last run** — a feed of
  *movement* within your filter set, not a one-time export. For the full current
  match set, use [Company Search](/company-docs/search/introduction).
</Note>

## Request body

| Field                        | Required | Description                                                                                                                                            |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filters`                    | Yes      | A filter tree, identical to [Company Search](/company-docs/search/reference). `{ "op": "and"\|"or", "conditions": [ { "field", "type", "value" } ] }`. |
| `config.trigger`             | Yes      | `{ "type": "interval", "every_hours": N }` — how often the watch runs (e.g. `1`, `6`, `24`, `168`).                                                    |
| `config.max_results_per_run` | No       | Max records delivered per run. Default `25`. The first (baseline) run is always capped at 5.                                                           |
| `config.expires_at`          | No       | ISO date (`"2027-01-01"`). The watch auto-stops after this date.                                                                                       |
| `notifications`              | Yes      | One or more delivery channels (see [below](#delivery-channels)).                                                                                       |

The response returns the watch `id`:

```json theme={"theme":"vitesse-black"}
{ "id": 46849 }
```

<Note>
  All examples require the headers `authorization: Bearer YOUR_API_KEY`,
  `content-type: application/json`, and `x-api-version: 2025-11-01`. For the
  full list of `field` values and operators, see the
  [Company Search reference](/company-docs/search/reference).
</Note>

## Company filter format

Watcher filters use the **exact same syntax and fields** as [Company Search](/company-docs/search/reference) — no new filter language to learn. Each filter is a tree of leaf conditions combined with `and` / `or` operator groups:

* **Leaf condition** — `{ "field": "...", "type": "...", "value": ... }`, where `field` is a company attribute (e.g. `headcount.total`), `type` is the operator (e.g. `=>`, `in`, `>`), and `value` is what to match.
* **Operator group** — `{ "op": "and" | "or", "conditions": [ ... ] }`, where `conditions` is a list of leaf conditions or nested groups. `and` requires every condition, `or` any one; nest groups for compound logic.

## Recipes

### Segment + headcount growth

New **Brazilian software companies (50–500 employees) that grew headcount 30%+**:

```bash theme={"theme":"vitesse-black"}
curl --request POST \
  --url https://api.crustdata.com/watch/company/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": "taxonomy.professional_network_industry", "type": "=", "value": "Software Development" },
        { "field": "locations.country", "type": "in", "value": ["Brazil"] },
        { "field": "headcount.total", "type": "=>", "value": 50 },
        { "field": "headcount.total", "type": "=<", "value": 500 },
        { "field": "headcount.growth_percent.6m", "type": "=>", "value": 30 }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 }, "max_results_per_run": 25 },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'
```

### Well-funded companies in a country

New **US companies that have raised more than \$10M**:

```bash theme={"theme":"vitesse-black"}
curl --request POST \
  --url https://api.crustdata.com/watch/company/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": "locations.country", "type": "in", "value": ["USA"] },
        { "field": "funding.total_investment_usd", "type": ">", "value": 10000000 }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" } ]
  }'
```

### Recently founded companies

New **companies founded after 2020**:

```bash theme={"theme":"vitesse-black"}
curl --request POST \
  --url https://api.crustdata.com/watch/company/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": "basic_info.year_founded", "type": ">", "value": 2020 },
        { "field": "taxonomy.professional_network_industry", "type": "=", "value": "Software Development" }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 168 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'
```

### High-growth mid-market

Software companies **growing fast in the 200–2,000 range**:

```bash theme={"theme":"vitesse-black"}
curl --request POST \
  --url https://api.crustdata.com/watch/company/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": "headcount.growth_percent.6m", "type": ">", "value": 15 },
        { "field": "headcount.total", "type": "=>", "value": 200 },
        { "field": "headcount.total", "type": "=<", "value": 2000 }
      ]
    },
    "config": { "trigger": { "type": "interval", "every_hours": 24 } },
    "notifications": [ { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" } ]
  }'
```

## Delivery channels

Every watch needs at least one channel in `notifications`. Add one or more; matches fan out to all of them.

<CodeGroup>
  ```json Webhook theme={"theme":"vitesse-black"}
  { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata", "headers": { "X-Watch-Name": "brazil-software-growth" } }
  ```

  ```json Slack theme={"theme":"vitesse-black"}
  { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" }
  ```

  ```json Multiple theme={"theme":"vitesse-black"}
  [
    { "type": "webhook", "url": "https://your-app.com/webhooks/crustdata" },
    { "type": "slack", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX" }
  ]
  ```
</CodeGroup>

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

## Manage a watch

<CodeGroup>
  ```bash List runs theme={"theme":"vitesse-black"}
  curl --request GET \
    --url 'https://api.crustdata.com/watcher/watches/46849/runs?limit=20' \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```

  ```bash Run detail (delivered records) theme={"theme":"vitesse-black"}
  curl --request GET \
    --url https://api.crustdata.com/watcher/watches/46849/runs/54811/summary \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```

  ```bash Cancel a watch theme={"theme":"vitesse-black"}
  curl --request DELETE \
    --url https://api.crustdata.com/watcher/watches/46849 \
    --header 'authorization: Bearer YOUR_API_KEY'
  ```
</CodeGroup>

## Pricing

|                                          | Credits  |
| ---------------------------------------- | -------- |
| First run (baseline, up to 5 matches)    | **Free** |
| Each new company delivered on later runs | **2**    |

You're charged only for companies actually delivered — never for a run that finds nothing new. See [Pricing](/general/pricing) for full details.

## Related

<CardGroup cols={2}>
  <Card title="Company entity watchers" icon="building" href="/watcher-docs/company/entity">
    Watch a known list of companies for profile changes.
  </Card>

  <Card title="Company Search" icon="magnifying-glass" href="/company-docs/search/introduction">
    Pull the full current set of matches in one call.
  </Card>

  <Card title="Company Search reference" icon="filter" href="/company-docs/search/reference">
    Every filter `field`, operator, and value.
  </Card>

  <Card title="Pricing" icon="coins" href="/general/pricing">
    Credit costs across all Crustdata endpoints.
  </Card>
</CardGroup>