Skip to main content
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).
1

Register a webhook endpoint

Register the HTTPS endpoint that should hear about updates, and store the returned secret — it appears once.
Verify the signature on every delivery — see Events & signatures.
2

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.
The response includes next_run_at. Each run monitors the profile for new information and appends what it finds — see watchers.
3

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

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:
For per-run detail (including billing), use watcher runs.
5

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

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.

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