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. A succeeded run costs the same however many searches it makes. 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 runs automatically, and a result must pass every applicable check to appear in changes:
  • Novelty: Whether the result adds new information.
  • Legitimacy: Whether the source is trustworthy.
  • Time window: Whether the result fits the run’s time window.
  • Relevance: Whether the result matches your instructions. This check applies only when you provide a goal.

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.