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

# Watch

> Watch a list of companies and get an event when something you care about changes.

> [!NOTE]
>
> **Coming Soon.** Watch is not available yet. This page describes how it is planned to work, so you can design for it. Details can change before release. To hear when it ships, email [support@avina.io](mailto:support@avina.io).

A search finds companies that match right now. Watch is for companies you already care about: it tells you when something changes at one of them.

You give Watch a list of companies and a condition. It checks the condition on a schedule and sends you an event when a company's answer changes, with the same kind of evidence a search result carries.

## What it is for

> [card] Track your accounts
>
> "Tell me when any account in my CRM starts hiring SDRs."

> [card] Watch a portfolio
>
> "Tell me when a portfolio company announces an acquisition."

> [card] React to each new occurrence
>
> "Tell me each time one of these companies posts a job for a Head of Data."

> [card] Keep a list current
>
> "Tell me when a company on this list stops matching the profile I built it from."

## How it will work

**1. Bring a list**

Start from the results of a search, or supply your own companies.

**2. Set a condition**

Use the same language as search: structured filters, free-text criteria, or both. For example, "has an open SDR job".

**3. Choose a trigger**

Fire when a company's answer **changes**, such as from not hiring to hiring. Or fire on each **new occurrence**, such as every new matching job.

**4. Receive events**

Read events from a feed, or have them sent to a webhook (A URL on your server that another service calls to tell you something happened.). Each event names the company, the condition, and the evidence.

A watch on two companies for a new Head of Data job:

```json POST /v1/companies/watches theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "is hiring a Head of Data",
  "company_domains": ["northwindpay.example", "ledgerline.example"],
  "trigger": "change",
  "frequency": "daily",
  "max_cost_usd": 5
}
```

When one of them posts the job, the watch records an event:

```json Planned event theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "watch_event",
  "id": "evt_5Rk8Wq2nD7",
  "type": "started_matching",
  "company": { "name": "Northwind Pay", "domain": "northwindpay.example" },
  "evidence": {
    "summary": "1 open job matches.",
    "sources": ["https://northwindpay.example/careers/head-of-data"],
    "items": [{ "type": "job", "title": "Head of Data", "posted_at": "2026-11-10" }]
  },
  "detected_at": "2026-11-12T06:00:14Z"
}
```

The full planned contract, with every field and the event feed, is in the [Watch reference](https://docs.data.avina.io/api-reference/watch.md).

## Design principles

* **Events on change only.** A company that keeps matching does not produce an event every day. You hear about it when the answer changes.
* **The first check sets the baseline.** It records where each company stands and sends no events.
* **Unknown is not a change.** If a check cannot be completed, no event is sent. A failed check never looks like a real change.
* **Spend limits.** Each check has its own spend limit in dollars, like a search.
* **Evidence on every event.** Each event carries the evidence for the condition, as search results do.

## Until it ships

[Monitor a search](https://docs.data.avina.io/guides/scheduled-searches.md) to keep finding new companies that match a condition. A monitored search runs again every day or every week and adds the new matches it finds.

That covers new companies. It does not tell you when a company you already track changes, which is what Watch adds.

> [card] [Companies](https://docs.data.avina.io/capabilities/companies.md)
>
> Available today.

> [card] [Changelog](https://docs.data.avina.io/changelog.md)
>
> Release announcements.


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