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

# Create a watch

> Watch a list of companies against a condition and get an event when a company's answer changes. Coming soon.

> [!NOTE]
>
> **Coming Soon.** Watch is not available yet, and these endpoints are not live. This page is the planned contract, published early so you can design against it. Fields can change before release. Watch is not part of the [OpenAPI specification](https://docs.data.avina.io/api-reference/openapi.md) until then.

A watch checks a fixed list of companies against a condition on a schedule. When a company's answer changes, the watch records an event with the evidence for it. You read events from a feed, or have them sent to a webhook.

The condition uses the same language as search: a plain-language `query`, or `filters` and `criteria`.

> [!WARNING]
>
> Each scheduled check is charged for the data it needs, at provider cost plus the 5% platform fee. Set `max_cost_usd` to cap each check. Reading a watch and its events is free. See [Pricing](https://docs.data.avina.io/concepts/pricing.md).

### Headers

**Idempotency-Key** `string`

A unique string for this request, 1 to 255 characters. Retrying with the same key and body returns the original watch instead of creating a second one.

### Body

**query** `string`

The condition to watch for, in plain language, such as "is hiring a Head of Data". Required unless you send `filters` or `criteria`. Cannot be combined with them.

Maximum 1,000 characters.

**filters** `object`

The condition as structured filters, in the same format as search. See the [filter reference](https://docs.data.avina.io/guides/structured-filters.md).

**criteria** `(string | object)[]`

The condition as free-text criteria, in the same format as search.

**company\_domains** `string[]`

The companies to watch, as website domains. Send this or `search_id`, not both.

1 to 500 items.

**search\_id** `string`

Watch the companies that a finished [company search](https://docs.data.avina.io/api-reference/companies/search.md) returned. Send this or `company_domains`, not both.

**trigger** `string` (default: change)

When to record an event.

* `change`: when a company starts matching the condition, and when it stops.
* `new_occurrence`: once for each new matching occurrence, such as every new job listing that fits.

**frequency** `string` (default: daily)

How often to check: `daily` or `weekly`.

**max\_cost\_usd** `number`

The most one scheduled check may spend, in US dollars, including the platform fee. A check that reaches the limit stops and reports which companies it did not get to.

**webhook\_url** `string`

A public `https` URL that receives a `POST` for each event. Requests are signed, so your server can confirm they came from Avina. The event feed remains the source of truth.

### Response

**`201`** The watch was created and its first check has started.

**object** `string` *required*

Always `watch`.

**id** `string` *required*

The watch's identifier.

**status** `string` *required*

`active` or `paused`.

**query** `string | null` *required*

The plain-language condition, when the watch was created with `query`.

**interpretation** `object | null` *required*

How a `query` was read, in the same shape as on a search.

**trigger** `string` *required*

`change` or `new_occurrence`.

**frequency** `string` *required*

`daily` or `weekly`.

**companies** `object` *required*

How many companies are being watched.

**properties**

**selected** `integer` *required*

Companies being watched.

**unresolved** `integer` *required*

Domains that could not be matched to a company. They are not watched.

**last\_run\_at** `string | null` *required*

When the last check finished.

**next\_run\_at** `string | null` *required*

When the next check is due. `null` while the watch is paused.

**cost\_usd** `number` *required*

What this watch has cost so far, in US dollars.

**created\_at** `string` *required*

When the watch was created.

**events\_url** `string` *required*

The URL of this watch's event feed.

## Read events

`GET /companies/watches/{watch_id}/events` returns the watch's events, oldest first. It is paginated with cursors in the same way as search results: pass the last `next_cursor` as `after` to read only new events. Reading events is free.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.avina.io/v1/companies/watches/$WATCH_ID/events?limit=25" \
  -H "Authorization: Bearer $AVINA_API_KEY"
```

```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": "1"
}
```

**type** `string`

* `started_matching`: the company did not match at the previous check and matches now.
* `stopped_matching`: the company matched at the previous check and does not match now.
* `occurrence`: a new matching occurrence, for watches with `trigger: new_occurrence`.

**company** `object`

The company the event is about.

**evidence** `object`

The evidence for the event, in the same shape as on a search result. See [Evidence and verdicts](https://docs.data.avina.io/concepts/evidence.md).

**detected\_at** `string`

When the check that found the change ran. A job listing or announcement can be older than this.

## How events are decided

* **The first check sets the baseline.** It records whether each company matches and sends no events. Events start with the second check.
* **Unknown is not a change.** If a check cannot confirm a company's answer either way, its last known answer is kept and no event is recorded.
* **One event per change.** A company that keeps matching does not produce an event at every check.

## Other operations

| Method | Path | |
| - | - | - |
| `GET` | `/companies/watches` | List watches |
| `GET` | `/companies/watches/{watch_id}` | Get a watch's settings and status |
| `PATCH` | `/companies/watches/{watch_id}` | Pause or resume, with `{ "status": "paused" }` or `{ "status": "active" }` |
| `POST` | `/companies/watches/{watch_id}/run` | Check now, without waiting for the schedule |
| `DELETE` | `/companies/watches/{watch_id}` | Delete a watch. Its events are no longer readable. |

### Errors

| Status | Code | When |
| - | - | - |
| `400` | `invalid_request` | The request is invalid, for example both `company_domains` and `search_id`, or more than 500 domains. |
| `401` | `invalid_api_key` | The API key is missing, invalid or revoked. |
| `402` | `usage_limit_reached` | The workspace's balance is used up. Nothing was created or charged. |
| `404` | `not_found` | No watch or search with that `id` in this workspace. |
| `409` | `idempotency_key_reused` | The `Idempotency-Key` was already used with a different request. |
| `429` | `rate_limited` | Too many requests. Retry after `Retry-After` seconds. |

Every error uses the same shape. See [Errors](https://docs.data.avina.io/api-reference/errors.md).

> [!NOTE]
>
> The companies, events and dollar amounts in these examples are illustrative.

```json JSON 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
}
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.avina.io/v1/companies/watches \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": "is hiring a Head of Data",
    "company_domains": ["northwindpay.example", "ledgerline.example"],
    "trigger": "change",
    "frequency": "daily",
    "max_cost_usd": 5
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import uuid
import requests

response = requests.post(
    "https://api.avina.io/v1/companies/watches",
    headers={
        "Authorization": f"Bearer {os.environ['AVINA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "query": "is hiring a Head of Data",
        "company_domains": ["northwindpay.example", "ledgerline.example"],
        "trigger": "change",
        "frequency": "daily",
        "max_cost_usd": 5,
    },
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch("https://api.avina.io/v1/companies/watches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    query: "is hiring a Head of Data",
    company_domains: ["northwindpay.example", "ledgerline.example"],
    trigger: "change",
    frequency: "daily",
    max_cost_usd: 5,
  }),
});
const data = await response.json();
console.log(data);
```

```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "watch",
  "id": "4a7d2e9c-1b3f-4c6a-9e8d-7f0a2b5c6d13",
  "status": "active",
  "query": "is hiring a Head of Data",
  "interpretation": {
    "filters": {
      "all": [
        {
          "related": {
            "relationship": "open_jobs",
            "where": { "all": [{ "field": "title", "operator": "in", "value": ["Head of Data"] }] }
          }
        }
      ]
    },
    "criteria": [],
    "unsupported_criteria": []
  },
  "trigger": "change",
  "frequency": "daily",
  "companies": { "selected": 2, "unresolved": 0 },
  "last_run_at": null,
  "next_run_at": "2026-11-13T06:00:00Z",
  "cost_usd": 0,
  "created_at": "2026-11-12T17:30:00Z",
  "events_url": "https://api.avina.io/v1/companies/watches/4a7d2e9c-1b3f-4c6a-9e8d-7f0a2b5c6d13/events"
}
```


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