Watch and refresh
POST /v1/watch: save a query, refresh it on your schedule and get back only the new and changed records.
A watch is a saved query whose reruns answer with what changed. The first run keys every record of the result on its own identity (a posting's URL, a profile's LinkedIn URL, an award's id, a USAJOBS control number) and stores a fingerprint per key. A refresh reruns the same query, bills like any run, and returns only the new and changed records, plus the keys that disappeared. Records are never copied: they stay on the run, and the changes are rebuilt from the last run's result when you ask.
Use it for the weekly loop behind monitoring: one watch per office, contractor, keyword or search, one refresh per week, and your pipeline reads the delta instead of the whole list. A watch never refreshes on its own: the refresh comes from your scheduler, cron job or routine.
Create a watch
POST /v1/watch
Same body as run plus a name: a capability with its input, or provider + endpoint with the provider's request for a raw endpoint. Set routing.max_cost from inspect, as on any run. record is refused; with tables on, into lands the records of every run in a table.
curl -X POST https://api.routergrowth.com/v1/watch \
-H "Authorization: Bearer $ROUTERGROWTH_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "Booz Allen program manager postings", "capability": "company.jobs",
"input": {"company": "Booz Allen Hamilton", "query": "program manager", "posted_within": "month", "limit": 20},
"routing": {"max_cost": "0.10"}}'
Answers 201 with the watch, the run receipt and the changes. On the first run every record is new.
{
"watch": {"watch_id": "wch_...", "name": "Booz Allen program manager postings", "kind": "capability",
"capability": "company.jobs", "key_field": "url", "records": 14, "runs": 1,
"last_changes": {"status": "succeeded", "new": 14, "changed": 0, "removed": 0, "unchanged": 0}},
"run": {"run_id": "run_...", "status": "succeeded", "billing": {"quoted": "0.0273", "charged": "0.0195"}},
"changes": {"counts": {"records": 14, "new": 14, "changed": 0, "removed": 0, "unchanged": 0},
"new": [{"title": "Senior Program Manager, Navy", "url": "https://...", "posted_at": "2026-09-15"}],
"changed": [], "removed": []}
}
Prices on this page are catalog prices, which start at the Scale plan rate; inspect returns your workspace's exact price.
The request waits up to wait_seconds (default 30, at most 120; "async": true answers at once). A run still going then answers 202 with changes: null and its id in watch.pending_run_id: GET /v1/watch/{watch_id}?wait=60 collects the changes once it finishes.
Watch official sources only
For a web.search watch on official sources, pass the domains and dates as input, not only as query text:
{"name": "SSC acquisition news", "capability": "web.search",
"input": {"query": "contract award", "include_domains": ["ssc.spaceforce.mil", "spaceforce.mil"],
"start_date": "2026-09-01", "limit": 10}}
include_domains (up to 10) keeps a domain and its subdomains. start_date and end_date (YYYY-MM-DD) bound the publication date. A query written the Google way, site:ssc.spaceforce.mil after:2026-09-01 contract award, is read the same way. The live routes (DataForSEO, Firecrawl, Apify) get them as site:, after: and before: operators. Every answer is then screened: results off the domains or outside the dates are removed. A provider whose results all fall outside is a free miss, and the next provider runs. The result's filters block reports what was removed (removed_off_domain, removed_out_of_range) and how many undated results were kept (kept_undated).
Refresh
POST /v1/watch/{watch_id}/refresh?wait=60
Reruns the query, always at the providers: a refresh is never answered from an earlier run or a table row. wait defaults to 30 seconds (at most 120) and a run still going answers 202 as above. changes.new holds records whose key was not there last time, changes.changed the records whose content moved, changes.removed the keys no longer returned. Top-level fields that drift between runs without meaning anything are ignored: position and rank, score and relevance, fetch times, image and avatar URLs, and an account's followers count. Engagement counts are content: a post whose likes or replies moved comes back in changes.changed. A refresh whose run fails changes nothing: the fingerprints stay, the next refresh diffs against them, and last_changes.error says what happened. A refresh while one is still executing answers 409 conflict.
changes.sources (and last_changes.sources on the watch) lists every provider the refresh tried, in order, with its outcome and detail: succeeded, no_match, provider_error, provider_rate_limited or provider_timeout.
Status: no match or incomplete
The status on changes and last_changes tells an empty answer from a missing one:
| Status | Meaning | Fingerprints |
|---|---|---|
succeeded |
a provider returned records | replaced by this run's records |
no_ |
every provider that ran answered with no result: the query has no records now | replaced (every known key is in removed) |
incomplete |
at least one provider failed (an upstream error, a dropped connection, a timeout) and the others found nothing, so the empty answer is not a finding | kept as they were |
failed, timed_, cancelled, blocked |
no provider answered, the run was cancelled, or a workspace control such as the spend guard stopped it | kept as they were |
An incomplete refresh reports no new, changed or removed records, and error names the providers that did not answer:
{
"status": "incomplete",
"error": "Incomplete: dataforseo did not answer, so this no_match covers only apify, firecrawl. The watch kept its last records; refresh again to retry.",
"counts": {"records": 4, "new": 0, "changed": 0, "removed": 0, "unchanged": 4},
"sources": [{"provider": "dataforseo", "outcome": "provider_error", "detail": "dataforseo 40101: Internal SE Server Error."},
{"provider": "apify", "outcome": "no_match", "detail": null},
{"provider": "firecrawl", "outcome": "no_match", "detail": null}]
}
Refresh again to retry; the next refresh diffs against the records the watch already had. The run receipt keeps the run's own status (no_match) with error code no_match_partial_coverage and coverage.status: "partial", so reading the run alone gives the same answer; an unmatched run charges nothing.
Read and list
GET /v1/watch?limit=50 every watch, newest first (200 at most), with counts and the last refresh summary, no records
GET /v1/watch/{watch_id} the watch, the last run receipt, the last changes with records; ?wait=60 holds while a refresh runs
DELETE /v1/watch/{watch_id} {"deleted": "wch_..."}
An unknown watch_id answers 404 not_found.
How records are keyed
| Result | Key |
|---|---|
| company.jobs, web.search, news.search, seo.serp, social.search, social.posts | the record's url |
| social.comments | the row's url, or the comment id when the row has no url |
| people.search | linkedin_ |
| linkedin.search | profile_ (the LinkedIn profile URL) |
USAJOBS / |
PositionURI; /: usajobsControlNumber |
| USAspending award search | generated_ |
Grants.gov / |
the opportunity id |
Federal Register / |
document_ |
Recherche d'entreprises / |
siren |
BODACC /, BOAMP /, DECP / |
id, idweb and uid respectively |
| any other list of records | the first identity field present, in this order: url, profile_, linkedin_, link, government record ids, id, job_, post_, place_, email, domain, name; else a hash of the record |
| a single-record answer (one enrichment, one page) | not a list: the watch diffs the longest list of records inside it (a profile's job history, for example), or reports zero records |
key_field on the watch tells you which one was used. A run's first 2,000 records are tracked. Two providers can name the same person differently; a watch diffs one query on one route, it does not merge identities across providers.
Cost
A watch costs nothing to keep. Each refresh is a run of the same query, priced and settled like any other run of it, so the weekly cost of a watch is the price of its query, and the delta is free. Cheap signal queries (postings, news, USAJOBS, awards) are the ones to refresh often; people lists are priced per person returned, so refresh them on a longer cadence.
Over MCP the same loop is the watch tool (create, or refresh with watch_id) and watches (list, or read one with watch_id). Delete a watch over REST or with routergrowth watches delete.
Reading this as an agent? This page as markdown: /docs/api/watch.md · every page: /docs/llms.txt