Skip to main content
A Search monitor runs web searches on a schedule and saves relevant findings. This tutorial creates a daily competitor news monitor using cURL and reads its results from run history.

What you will build

This monitor looks for a competitor’s product launches, availability announcements, and business news. Close your terminal after creating it and read the results later.
This example uses one Search target across the web without a webhook. Use webhooks to receive change notifications without polling for results.
For query options, filters, and deduplication, see the Search guide.

Prerequisites

Use Bash, cURL, and jq, and a Perplexity API key with enough credits for recurring checks. Review Monitor API pricing before starting. API organizations requiring zero data retention cannot create, resume, or manually run monitors.

Set up your API key

Use a secret manager or configure your shell to avoid saving the key in history. Replace YOUR_API_KEY with your Perplexity API key and run the following commands in the same shell.

Create the monitor

Creation makes the first run due immediately and leaves daily checks active. The run starts asynchronously. Pause the monitor when your trial is finished. The example query finds Samsung product and business news. Its goal asks the judge to keep substantive, verified reports and exclude rumors, reviews, and duplicate coverage. To monitor another competitor, change the name, query, and goal to match the company and developments you care about.
Example response (excerpt):
This example monitor was later paused and deleted. Copy the id returned by your own create request into the prompt below; the remaining commands act on the monitor you supply.
After entering the ID, run the next block.

Daily window and freshness

The first run looks back one schedule period before creation, up to seven days. With 1d, that first window is one day, so older news may not appear and the first run can return no findings. Later runs normally continue from the previous successful window, subject to the service’s lookback limit. See freshness and run windows for details. 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. URLs already reported by this monitor remain suppressed, so updated does not report later edits to a previously reported URL.

Check the monitor’s status

Retrieve the saved monitor to confirm its goal, targets, and schedule. The create response starts asynchronous work; it does not contain a finished reading list.
status: active means scheduled checks are enabled, while status: paused means they are stopped. Use current_run_id to see whether a run is queued or running, last_run for the last finished run, and next_run_at for the next scheduled check. Fields that do not apply are omitted. If the monitor is paused unexpectedly, inspect pause_reason before resuming it. See automatic pausing for causes and recovery steps.

Read the findings

Read the run history after creation. This GET request retrieves stored work and does not trigger another search.
Example response (excerpt):
The excerpt omits fields, the finding’s snippet, and the other 14 changes; the counts describe the full run. Runs are returned newest first. If the list is empty or a run is still queued or running, repeat the same read-only request later. Check each run’s status before reading its findings:
  • succeeded: Read changes[] and inspect counts and target_errors. An empty changes array means the run kept no results for your goal within the run window. Empty runs are normal when there are no new relevant results under your chosen freshness filter; indexing can also affect which results appear.
  • failed or skipped: Read the run’s error. Do not count it as a successful check.
  • queued, running, or an unknown status: Do not treat the run as finished.
A Search finding has type: search_result, a source url, a stable id, and a confidence score. It may also include title, snippet, and source-date fields. The judge checks whether a candidate comes from a legitimate source, is novel, and falls within the run window. When a goal is set, as in this example, it also checks relevance to that goal. Each check must meet its own threshold; confidence is the product of the check scores. The query supplies the topic, while goal guides which candidates are kept.

Receive results with webhooks

To receive notifications, add a public HTTPS receiver that you control. See webhook notifications for configuration, delivery, and signature verification.

Run a check now

After the first run finishes, you can request another check without waiting for the daily schedule. A manual run incurs usage costs just like a scheduled run.
An HTTP 202 response means the run is queued. Read its result using the run-history request above. If a run is already queued or running, the request returns HTTP 409; check current_run_id in the monitor status, wait for that run to finish, and try again if you still need another check.

Pause when finished

Pause the monitor to stop scheduled checks while retaining its state and saved history. A queued run is cancelled; a run already in progress can finish.
Check that the response has status: paused. You can also repeat the earlier GET monitor request to verify its saved status. Example response (excerpt):

Optionally delete it

Deletion also removes run history and saved state. Export any findings you need before executing this command.
Check for the same monitor ID and deleted: true in the response. Do not delete the monitor if you still need its history for review. Example response (excerpt):
If you delete your own monitor, use its ID when checking the response.

Limits

The example searches across the web. Results depend on indexing and source dates, and previously reported URLs are suppressed. Runs are retained for 90 days. Scheduled work continues after your shell exits, so pause the monitor when finished and export any history you want to keep. See Monitor API limits for request and active-monitor limits, and Manage monitors for updates and resuming checks. The API reference lists the complete request and response fields.