Watching

A watched audience re-runs on a schedule and tells you who is new since the last run. Each run re-checks the audience against its filters as of that day (a window such as active_within_days counts back from the run, not from when you built it) and looks at up to 500 of the leads that match now.

Start watchingCopy Anchor Link

The audience must be ready. Send a watch object to PATCH /v1/audiences/{id}:

{
  "saved": true,
  "watch": { "interval": "week", "auto_reveal": true, "cap": 200 }
}

Send "watch": null to stop. The audience stays saved. In the app, use Save & watch on an audience. Over MCP, use the watch_audience tool, which has no default cap: the assistant must pass a budget you agreed to.

What a run doesCopy Anchor Link

1. The first run after you start watching is a baseline: it marks everything the audience already holds as seen. It finds no new leads and spends nothing.
2. Every later run looks for leads this audience has never delivered before. Those are its new_count, at most 500 per run. They are added to the audience, so you can preview and Reveal them like the rest.
3. With auto_reveal, the run Reveals up to cap of them, 1 chip each (leads you already unlocked are free). If the balance can't cover them, every new lead stays masked and the chips.low event fires.
4. New leads past the cap stay masked. Reveal them later from the audience as usual.
5. The run sends audience.new_leads with the revealed leads in full, masked_count, and a reveal_url for the rest, and emails the workspace owners a digest (at most one per audience per day).

next_run_at on the audience says when the next run starts, and last_run shows the most recent one. A failed run moves on to the next slot, and its leads are found again next time.

CostsCopy Anchor Link

Watching itself is free. Only auto-revealed leads cost chips, never more than cap per run.