Skip to main content
A watcher checks one Orbit profile on a schedule you choose. Each run adds new information about the person to the profile. Create watchers with the watchers API, and see or manage them any time in Dashboard → Watchers.

​
Monitoring scope

By default a watcher monitors everything. The phases field can restrict it to a subset: New information appears on the profile and in its events timeline.

​
Where updates surface

  • sections.eventsTimeline in profile reads — dated event entries that are created or merged as new information arrives. Each event carries its date with datePrecision and dateBasis, the sources the event rests on, and can carry changes describing which source produced it and what kind of change it was.
  • profile.updated webhooks — delivered when a run finds new information. See webhook events.
  • Run history — GET /v3/watchers/{id}/runs lists every run with its outcome and a structured changes array.
  • Dashboard — the Watchers tab shows each watched profile with live refresh activity, and lets you pause, resume, retime, or delete watchers.
New events are searchable right away and appear in the events timeline. Other profile sections (jobs, passions, and so on) pick them up on their next regeneration. Every change is one of three kinds:

​
Directory watchers

A directory in the dashboard can watch its people as a group. Directories → (directory) → Watchers watches selected or all members on one schedule, keeps a default schedule and default checks for that directory, and shows an Updates feed: every dated event for every member, newest first, each with the sources behind it. People who can open the directory see the same events as an Activity view next to search, with unread markers. Directory watchers are managed in the dashboard; the watchers API creates and manages watchers per profile.

​
Scheduling

interval_seconds controls how often the watcher runs, from 3600 (hourly) to 2592000 (every 30 days). next_run_at on the watcher tells you when the next run is due. Each profile has one watcher per organization. Creating a watcher for a profile you already watch updates that watcher and turns it back on.

​
Billing

Watchers use credits from your organization’s balance. Each run costs 1 credit, plus 5 credits when it finds new information. Each run’s charge_amount is listed in watcher runs. You pay for completed runs. When your credits run out, the watcher pauses (enabled: false, paused_reason: "insufficient_credits"). Resume it after you top up.

​
Pausing and deleting

Set enabled: false via PATCH /v3/watchers/{id} to pause a watcher. Its settings and history stay. Set enabled: true to resume. DELETE removes the watcher; the profile stays.
Watcher endpoints require an API key with the watchers:write scope. Webhook registration requires webhooks:write. See Get API key.