> ## 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.

# Watch a profile for real-time updates

> Set up a watcher and a webhook so your application hears when new information about a profile is found — then read the updates from the events timeline.

This guide wires up the full loop: watch a profile, get notified when something new is found, and read the structured updates. You need an API key with the `watchers:write` and `webhooks:write` scopes ([get one here](/api/api-keys/create)).

<Steps>
  <Step title="Register a webhook endpoint">
    Register the HTTPS endpoint that should hear about updates, and store the
    returned `secret` — it appears once.

    ```bash theme={"dark"}
    curl -X POST "https://api.orbitsearch.com/v3/webhooks" \
      -H "Authorization: Bearer $ORBIT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"url": "https://example.com/orbit/webhooks", "event_types": ["profile.updated"]}'
    ```

    Verify the signature on every delivery — see
    [Events & signatures](/api/webhooks/events).
  </Step>

  <Step title="Create the watcher">
    Use the profile `id` from a search or profile read. Daily is a good
    starting cadence; the range is hourly to every 30 days.

    ```bash theme={"dark"}
    curl -X POST "https://api.orbitsearch.com/v3/watchers" \
      -H "Authorization: Bearer $ORBIT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"orbit_id": "83f1b564-3607-4618-b8c9-a886410ceb32", "interval_seconds": 86400}'
    ```

    The response includes `next_run_at`. Each run monitors the profile for
    new information and appends what it finds — see
    [watchers](/concepts/watchers).
  </Step>

  <Step title="Handle profile.updated">
    When a run adds new events, your endpoint receives a signed
    `profile.updated` delivery carrying the events themselves — each with its
    title, `date` (+ `datePrecision`, `dateBasis`), and `sources` — in the
    exact shape profile reads return in `sections.eventsTimeline`.

    Deduplicate on `x-orbit-webhook-event-id` (retries reuse it), respond
    `2xx` fast, and process asynchronously.
  </Step>

  <Step title="Read the updates">
    The webhook already carries the new events; `sections.eventsTimeline` on
    any profile read returns the same objects, with the profile's full
    history — dated events that are created or merged as new information
    arrives, newest first:

    ```bash theme={"dark"}
    curl "https://api.orbitsearch.com/v3/enrich/83f1b564-3607-4618-b8c9-a886410ceb32" \
      -H "Authorization: Bearer $ORBIT_API_KEY"
    ```

    ```json theme={"dark"}
    {
      "kind": "event",
      "title": "Example announces new venture",
      "description": "Example Person announced a new venture in July 2026...",
      "date": "2026-07",
      "datePrecision": "month",
      "dateBasis": "stated",
      "eventKey": "example-announces-new-venture",
      "updateCount": 2,
      "lastUpdatedAt": "2026-07-16T21:07:46.000Z",
      "changes": [
        {
          "sourceLink": "https://news.example.com/story",
          "sourceName": "Example News",
          "changeKind": "new_source",
          "summary": "Coverage of the announcement..."
        }
      ]
    }
    ```

    For per-run detail (including billing), use
    [watcher runs](/api/watchers/runs).
  </Step>

  <Step title="Manage watchers in the dashboard">
    **Dashboard** → **Watchers** shows every watched profile with live refresh
    activity, and lets you pause, resume, change intervals, and delete watchers.
  </Step>

  <Step title="Watch a whole directory">
    To watch many people at once, open a directory and use its **Watchers**
    tab: pick people (or all of them) and a schedule, and set the directory's
    default schedule and checks so new members are easy to add. The tab's
    **Updates** feed lists every member's dated events with their sources, and
    members of the directory see the same events in its **Activity** view.
  </Step>
</Steps>

## Cost control

Each run costs 1 credit, plus 5 credits when it finds something new. A quiet profile checked daily costs about 30 credits a month. To spend less, widen `interval_seconds` or limit `phases` (for example, `existing_socials` to watch social activity). When credits run out, watchers pause; resume them with `{"enabled": true}` after topping up. See [Credits and limits](/concepts/credits).