Skip to main content
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 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.
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.

Headers

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

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.
object
The condition as structured filters, in the same format as search. See the filter reference.
(string | object)[]
The condition as free-text criteria, in the same format as search.
string[]
The companies to watch, as website domains. Send this or search_id, not both.1 to 500 items.
string
Watch the companies that a finished company search returned. Send this or company_domains, not both.
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.
string
default:"daily"
How often to check: daily or weekly.
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.
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.
string
required
Always watch.
string
required
The watch’s identifier.
string
required
active or paused.
string | null
required
The plain-language condition, when the watch was created with query.
object | null
required
How a query was read, in the same shape as on a search.
string
required
change or new_occurrence.
string
required
daily or weekly.
object
required
How many companies are being watched.
string | null
required
When the last check finished.
string | null
required
When the next check is due. null while the watch is paused.
number
required
What this watch has cost so far, in US dollars.
string
required
When the watch was created.
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.
cURL
200
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.
object
The company the event is about.
object
The evidence for the event, in the same shape as on a search result. See Evidence and verdicts.
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

Errors

Every error uses the same shape. See Errors.
The companies, events and dollar amounts in these examples are illustrative.