{
"query": "is hiring a Head of Data",
"company_domains": ["northwindpay.example", "ledgerline.example"],
"trigger": "change",
"frequency": "daily",
"max_cost_usd": 5
}
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
}'
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())
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);
{
"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"
}
Create a watch
Watch a list of companies against a condition and get an event when a company’s answer changes. Coming soon.
{
"query": "is hiring a Head of Data",
"company_domains": ["northwindpay.example", "ledgerline.example"],
"trigger": "change",
"frequency": "daily",
"max_cost_usd": 5
}
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
}'
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())
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);
{
"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"
}
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.
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
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
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.The condition as structured filters, in the same format as search. See the filter reference.
The companies to watch, as website domains. Send this or
search_id, not both.1 to 500 items.Watch the companies that a finished company search returned. Send this or
company_domains, not both.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.
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.
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.
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
curl "https://api.avina.io/v1/companies/watches/$WATCH_ID/events?limit=25" \
-H "Authorization: Bearer $AVINA_API_KEY"
200
{
"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"
}
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 withtrigger: new_occurrence.
The evidence for the event, in the same shape as on a search result. See Evidence and verdicts.
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. |
The companies, events and dollar amounts in these examples are illustrative.
{
"query": "is hiring a Head of Data",
"company_domains": ["northwindpay.example", "ledgerline.example"],
"trigger": "change",
"frequency": "daily",
"max_cost_usd": 5
}
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
}'
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())
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);
{
"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"
}

