Skip to main content
A Page monitor checks public web pages on a schedule and saves meaningful changes. This tutorial uses cURL to watch the Perplexity API docs and read findings from run history.

What you will build

This monitor watches the Perplexity API changelog, pricing guide, and Agent API quickstart for releases, deprecations, pricing changes, and changes to parameters or endpoints. Close your terminal after creating it and read the results later.
This example uses three Page targets without a webhook. Use webhooks to receive change notifications without polling for results.
For target options and how page comparisons work, see the Page 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 target URLs identify the pages to check. The goal asks the judge to keep substantive API changes and ignore cosmetic ones. To monitor other pages, change the name, URLs, and goal to match the pages and changes you care about.
Example response (excerpt):
This example monitor was later paused and deleted. Copy the id from your own response into the prompt below; the remaining commands act on the monitor you supply.

The first run and later checks

The first run saves a baseline for each page it successfully reads and reports no page changes for those pages. Existing content becomes part of the baseline. Later checks compare each page with its saved state. The judge assesses detected changes against the goal; an empty result can mean the pages did not change or no detected changes were kept. See the first Page run for baseline behavior.

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 result.
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 page check.
Example first run (excerpt from the run history):
This first run established the page baselines. The excerpt omits other run fields. 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 is expected for the first successful baseline and can also occur on later checks when no relevant changes are kept. Check target_errors before treating an empty result as a successful check of every page.
  • 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 Page finding has type: page_change, a source url, a stable id, and a confidence score. It includes previous_fetched_at and fetched_at for the compared snapshots, and a diff of normalized page text. The page title may also be included. The diff contains unified text plus added_lines, removed_lines, and truncated. The unified diff is limited to 24 KiB (24,576 UTF-8 bytes). Truncation keeps complete lines where possible; an oversized line can be shortened at a UTF-8 character boundary. The line counts still describe the full diff. This diff shows a quickstart changing from presets to effort levels:
A unified diff includes hunk headers and context lines. The judge scores whether the change is meaningful against the goal and keeps it when the score meets the threshold. The confidence score ranges from 0 to 1.

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 can incur usage costs just like a scheduled run.
An HTTP 202 response means the run is queued. Read its result through run history. If another run is already queued or running, follow its current_run_id instead; see Run now for response handling.

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:

Limits

The example watches three public pages. A Page Monitor can have up to 10 distinct public HTTP or HTTPS URLs, but Page targets cannot be mixed with a Search target. 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. Page snapshots expire 90 days after the last run that wrote them; a monitor paused longer than that starts from a fresh baseline when resumed. 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.