You need
- An API key. See the quickstart.
- A balance in your workspace. Every scheduled run is charged like a search. Set
max_cost_usdto cap each run.
Start a monitored search
Addmonitor to the request that starts the search. The search runs straight away, then again at the frequency you chose.
monitor:
Response (shortened)
id. Every run adds to this one search.
Monitor a search you already ran
Ran a search once and liked the results? Turn monitoring on for it:Frequencies
The schedule is counted from the moment monitoring was turned on.
monitor.next_run_at always shows when the next run is due. Daily and weekly are the options available today.
What happens at each run
1
The search starts again
At
next_run_at, the search’s status goes back to running.2
It looks only for new matches
Companies or people already in the results are skipped. They are not checked or charged for again.
3
New matches are added to the results
Each run adds up to
limit new results, after the ones that were already there.4
The run finishes
status becomes completed, stop_reason says why this run stopped, and monitor.next_run_at moves to the next run.stop_reason: sources_exhausted and the search tries again at the next run.
Read what each run found
Results from every run are in one list, in the order they were found. Store thenext_cursor you last saw and pass it as after, and you get only what has been added since. This is the same that Poll and paginate uses.
Python
found_at timestamp, so you can also tell which run it came from.
Webhooks that tell you when a run has finished are coming soon. Until then, read results on your own schedule, a little after
monitor.next_run_at.Control what it spends
A monitored search keeps spending until you pause or stop it, so set its limits when you create it.
A daily search with
max_cost_usd: 20 can spend at most $20 a day. cost_usd on the search is the total across all runs.
If your workspace’s balance runs out, the run stops and the schedule stays in place. The search tries again at its next run.
Pause, change or stop
Pausing keeps the schedule but skips runs. Stopping removes the schedule. In both cases, everything found so far stays readable.
Good to know
- The request is fixed. A plain-language
queryis interpreted once, when the search is created, so every run checks the same requirements. To change the requirements, start a new search. - Contacts come with new companies. If the search has
persona_ids, each new company arrives with its contacts, as on a one-time search. - People searches work the same way. Use
/people/searchin place of/companies/search. A monitored people search is a simple way to hear about people who have just started in a role. - It finds new matches, not changes. A monitored search adds companies that newly match. It does not tell you when a company already in your results changes. That is what Watch is for.
Related
- Signals: searches worth scheduling
- Monitor a company search and Monitor a people search
- Search lifecycle
- Pricing

