Skip to main content
A search normally runs once. When you monitor a search, it runs again on a schedule, and each run adds companies or people that match and were not in the results before. You can run a monitored search daily or weekly. Use it to keep a list growing without resending the request yourself: new companies hiring for a role, newly funded companies in your market, people who have just started in a job you sell to.
You need
  • An API key. See the quickstart.
  • A balance in your workspace. Every scheduled run is charged like a search. Set max_cost_usd to cap each run.
Add monitor to the request that starts the search. The search runs straight away, then again at the frequency you chose.
The response is the usual search, with its schedule in monitor:
Response (shortened)
Keep the search 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:
The companies it already found stay in the results. Later runs add to them.

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.
A run that finds nothing new is normal. It ends with 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 the next_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
Each result has a 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 query is 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/search in 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.