Skip to main content
PUT
Monitoring turns a one-time search into a scheduled one. At each run, the search looks for companies that match and are not already in its results, and adds up to limit new ones. Read them from the same results endpoint, passing your last next_cursor as after. Send this request for any search that has finished, or set monitor when you start the search. Sending it again changes the frequency, or pauses and resumes the schedule.
Every run is charged like a search. The search’s max_cost_usd applies to each run. See Scheduled searches.

Example bodies

Path parameters

string
required
The search’s id, returned when it was started.

Body

string
required
How often the search runs again. daily runs every 24 hours and weekly every 7 days, counted from when monitoring was turned on.
boolean
default:"false"
true keeps the schedule but skips runs until you set it back to false.

Response

200 The search, with its schedule in monitor.
string
required
company_search or people_search.
string
required
The search’s identifier. Use it to read status and results.
string
required
queued and running are in progress. completed, failed and cancelled are terminal. completed means this run finished, not that every matching record in the world was found. A monitored search goes back to running at its next scheduled run.
string | null
required
Why a finished search stopped. null while it is in progress. Can also be null on a failed search; read error.Options: target_reached, sources_exhausted, usage_limit_reached, retrieval_limit_reached, query_needs_clarification, provider_failed, cancelled.
string | null
required
A message when status is failed. Results found before the failure stay readable.
string | null
required
The natural-language request, when the search was started with query.
integer
required
The most results this search will return.
object | null
required
How a query was read. null until the query has been interpreted, and for searches started with filters or criteria.
object[]
required
Ambiguous wording in the query and how it was read.
object
required
Counts so far. They only increase.
number
required
What this search has cost so far, in US dollars, including the 5% platform fee.
boolean
required
true after a cancel request, until the search reaches cancelled.
object | null
required
The schedule, when the search is monitored. null for a search that runs once. On a monitored search, status and stop_reason describe the most recent run, and progress and cost_usd are totals across all runs.
string
required
When the search was started.
string | null
required
When the search reached a terminal status.
string | null
required
When the search and its results stop being readable. null when no expiry is set.
string
required
The URL of this search’s status.
string
required
The URL of this search’s results.

Errors

Every error uses the same shape. See Errors.