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.
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. ReplaceYOUR_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.id returned by your own create request into the prompt below; the remaining commands act on the monitor you supply.
Daily window and freshness
The first run looks back one schedule period before creation, up to seven days. With1d, 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.queued or running, repeat the same read-only request later.
Check each run’s status before reading its findings:
succeeded: Readchanges[]and inspectcountsandtarget_errors. An emptychangesarray 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.failedorskipped: Read the run’serror. Do not count it as a successful check.queued,running, or an unknown status: Do not treat the run as finished.
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.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.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.deleted: true in the response. Do not delete the monitor if you still need its history for review.
Example response (excerpt):