Create a Search monitor
Use cURL and jq, and setPERPLEXITY_API_KEY to your API key. Creating a monitor makes its first run due immediately and schedules later runs until you pause or delete it; see Monitor API pricing.
cURL
200 response is a monitor, not a completed run. Set MONITOR_ID to its id for the requests below.
Use an idempotency key if your application retries creation.
This example reads results through the API without configuring a webhook. Use webhooks to receive change notifications without polling for results.
Read the results
A run is one execution of a monitor. Itschanges array contains the Search results it kept. Retrieve the latest run using MONITOR_ID; the first run starts asynchronously after creation, so do not submit another /run request for it.
The two responses below show the same run. Use the IDs returned by your own requests.
cURL
List runs response
List runs response
queued, running, or an unknown status, keep polling with a bounded retry policy. For failed or skipped, inspect error; a succeeded run can have an empty changes array.
Set RUN_ID to the run ID in data[0].id, then retrieve that run. Run history is retained for 90 days.
cURL
Get run response
Get run response
usage.searches in the run response for the count.
Configure your search
Put one target withtype: "search" in targets.
Queries and goals
The query supplies the topic, and an optionalgoal describes which results to keep. Judging checks source legitimacy, whether the result adds new information, and whether it fits the run’s time window. When you provide a goal, it also checks relevance to your instructions.
Freshness
The freshness filter chooses which pages fall in the run window:published finds newly published pages, updated finds recently updated pages, and using both includes either. Updated dates have day-level precision.
The monitor uses its schedule and prior successful run to set a run window. Before the first successful run, the window starts one schedule period before creation, up to seven days earlier. Later windows normally start where the last successful window ended, subject to the service’s lookback limit. The window ends when the run starts.
Domain filters
Supply bare host names such asexample.com, without a scheme, path, or port. Each entry also covers its subdomains.
Deduplication and results
Search monitors deduplicate normalized URLs, both within a run and against previously seen URLs. Changing the goal does not replay seen URLs. Selectingupdated freshness still deduplicates known URLs; use Page monitoring to watch for later edits at a known URL.
Seen-URL state is retained for 90 days and refreshed when a URL is encountered again. You can update the query while keeping that history, or create a new monitor for fresh discovery history.
Update your search
Replace the Search target to change the query and restrict its sources:cURL
max_results resets it to 20. Without filters, both freshness modes apply and domain restrictions are removed; omitting an individual filter resets that filter to its default. An empty or null targets value is invalid.
You can update the goal separately without replacing the target. Deduplication still applies, so changing the goal does not replay seen URLs.
Next steps
Pause the monitor when you finish trying it. You can also change its schedule, add webhooks, or check the API reference for the full contract.Track competitor news
Create a daily monitor for a competitor’s product launches and business news.