Signup comes with $1 in credit. No subscription needed.Claim your $1
Docs: Watch and refresh
API reference

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_match 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_out, 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_url
linkedin.search profile_url (the LinkedIn profile URL)
USAJOBS /search PositionURI; /historicjoa: usajobsControlNumber
USAspending award search generated_internal_id
Grants.gov /search2 the opportunity id
Federal Register /documents.json document_number
Recherche d'entreprises /search siren
BODACC /records, BOAMP /records, DECP /data/ id, idweb and uid respectively
any other list of records the first identity field present, in this order: url, profile_url, linkedin_url, link, government record ids, id, job_id, post_id, place_id, 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