Skip to main content
A Search monitor runs a query on a schedule and saves new, relevant results. Use it to follow a topic across the web; use Page monitoring to track later edits at known URLs.

Create a Search monitor

Use cURL and jq, and set PERPLEXITY_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
The 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. Its changes 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
If the list is empty, read it again later. For 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
Each result includes a URL and a confidence score. Every run includes usage and cost. Check usage.searches in the run response for the count. Put one target with type: "search" in targets.

Queries and goals

The query supplies the topic, and an optional goal 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 as example.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. Selecting updated 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. Replace the Search target to change the query and restrict its sources:
cURL
Repeat the target’s required fields and any nondefault options you want to keep. Omitting 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.