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 sections — a run that changes what a section says (a new job, a new accomplishment, an updated net-worth range) rewrites that section, and the run reports it as a section_updated change naming the section and how many items were added or removed.
  • 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. The sections the run’s findings affect (jobs, education, accomplishments, and so on) are rewritten in the same run, and each section that changed is reported alongside the events. Every change is one of four kinds: Updates are reported through the fields where they appear on the profile. One job update that adds a job to the jobs section and an event to the timeline produces one section_updated change and one event.

​
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 completed run uses the watcher-run rate, plus the watcher-update rate when it finds new information: a recent or upcoming event, a changed section, a new source, or new social activity. See API credits for current rates. Each run’s charge_amount is listed in watcher 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.