> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How profile watchers keep Orbit profiles fresh

> Watchers monitor a profile on a schedule you choose and notify you through webhooks and the events timeline when new information is found.

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](/api/watchers/create), 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:

| Phase              | Monitors                                  |
| ------------------ | ----------------------------------------- |
| `existing_sources` | Updates to sources already on the profile |
| `existing_socials` | The person's social activity              |
| `new_sources`      | New sources about the person              |

New information appears on the profile and in its events timeline.

## Where updates surface

* **`sections.eventsTimeline`** in [profile reads](/api/enrich/read-profile#profile-sections) — 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](/api/webhooks/events).
* **Run history** — [`GET /v3/watchers/{id}/runs`](/api/watchers/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:

| `change_kind`   | Meaning                                      |
| --------------- | -------------------------------------------- |
| `new_source`    | A newly discovered source about the person   |
| `source_update` | An update to a source already on the profile |
| `social_post`   | New social activity                          |

## 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](/api/watchers/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}`](/api/watchers/update) to pause a watcher. Its settings and history stay. Set `enabled: true` to resume. [`DELETE`](/api/watchers/delete) removes the watcher; the profile stays.

<Note>
  Watcher endpoints require an API key with the `watchers:write` scope. Webhook
  registration requires `webhooks:write`. See [Get API key](/api/api-keys/create).
</Note>