Skip to main content
Monitor API checks the web on a schedule and saves results for you to read through the API. Choose Search to discover URLs for a query, or Page to track text changes at URLs you already know. You can also set up monitors in the API Console.

Choose a monitor type

Search

Find relevant web results over time.

Page

Track text changes to pages you already know.
Each monitor has either one Search target or 1 to 10 Page targets. You cannot mix the two types in one monitor.

How monitoring works

Create a monitor with your targets and schedule, and add a goal to describe the results you want. Its first run becomes due immediately and starts asynchronously; later runs follow the schedule until you pause or delete the monitor. A run is one execution of a monitor. The monitor carries saved state from one run to the next to identify new findings or page changes. See Search run windows and Page comparisons. The run saves kept findings in changes and any Page fetch or processing errors in target_errors. Read stored runs through the API, or configure webhooks for notifications.

Quickstart

Create a Search monitor and read its first results. To track changes at known URLs instead, follow the Page quickstart. You need cURL, jq, and a Perplexity API key. Set the key in your environment:

Create a monitor

This request creates a Search monitor and returns its configuration. To read the results, use the Check results request below.
cURL
Set MONITOR_ID to the returned id:

Check results

Read the latest run:
cURL
Pause the monitor when you finish trying it. The Search guide covers filters and query options; the Page guide covers known URLs and text changes.

Run status and history

For queued or running, retrieve the run again later using a bounded retry policy. Treat an unknown status as unfinished. Run history is retained for 90 days. Both monitor and run lists accept limit (default 20, capped at 100) and after. When has_more is true, pass the last entry’s id from data as after to read the next page.

Schedules

Set schedule.type to interval and choose an interval such as 1h, 6h, 1d, or 1w. Creation makes the first run due immediately; the interval controls later runs. To check once a day, update the monitor with:
cURL

Run now

After the initial run finishes, you can request a manual run of an active monitor. The 202 response is the queued run, not its completed result:
cURL
Use the returned run id with Get a run. If a run is already queued or running, the request returns 409 with error.type: "run_in_progress" and error.current_run_id; follow that run instead of retrying in a loop. A paused monitor returns 409 invalid_state; resume it before requesting a run.

Goals and judging

Use a goal to describe which findings matter to you. Update it without replacing the monitor. Sending an empty string clears the goal:
cURL
Judging runs automatically for Search results and Page changes before they appear in changes. When you provide a goal, it checks whether findings match it; judging still applies without a goal. Search and Page use different checks. See Search judging or Page judging for how each type uses the goal.

Manage monitors

Retrieve the monitor to check its configuration and status:
cURL
Use PATCH to update a monitor. See Update a monitor for supported fields and request examples.

Pause and resume

Pause stops scheduled runs and preserves monitor state. A queued run becomes skipped; a run already executing can finish.
cURL
Resume a paused monitor after resolving any automatic-pause cause. If you paused it manually, resume it when you want scheduled runs to start again.
cURL
Resume returns the monitor to active and recomputes its next run time. State can expire after a pause longer than 90 days, so a Page monitor can establish a fresh baseline rather than report a change from the old one.

Delete and clean up

Delete a monitor when you no longer need it. Deletion removes the monitor, its run history, and its state, and stops future scheduling:
cURL
Keep any results your application needs before deleting the monitor.

Error handling

HTTP errors use an error object with message, type, and numeric code. Validation errors can also identify param. A failed run has error.code and error.message; a skipped run instead has error.skip_reason and error.message. Use the typed code or reason for decisions, not the message text.

Automatic pausing

A monitor can pause automatically when its sources or a configured webhook keep failing, a credit check denies a run, or organization policy blocks execution. The monitor changes to status: "paused", sets pause_reason, and stops scheduling runs; next_run_at is omitted. Read the monitor’s pause_reason to identify what needs attention. A failed or skipped run does not, by itself, mean that the monitor is paused. A webhook delivery counts as failed only when it ends, after any applicable retries; individual retry attempts do not count separately. A successful run with no changes is not a source failure. After fixing the cause, resume the monitor to restore its schedule and clear its failure counts. Adding credits or fixing a receiver does not automatically resume a paused monitor.

Webhook notifications

Webhooks are optional for both Search and Page. You can add a webhook after creating a monitor and continue reading results through the API.

Configure a webhook

Set webhook.url to a public HTTPS receiver that you control, without embedded credentials and no longer than 2,048 bytes:
cURL
When you attach a webhook without a supplied secret, the response includes a one-time signing secret:
Store webhook.secret securely. A generated secret is returned only in the response to the create or attach request, not by later reads or an idempotent replay. You can also supply your own signing secret; it is never echoed. Use webhook updates to rotate a secret. When no webhook is configured, monitor responses omit the entire webhook field. On creation, omitting webhook or sending null selects this behavior; an empty object or empty URL is invalid.

Events

By default, a configured webhook subscribes to monitor.changes.detected and monitor.paused. Set webhook.events to choose the events you want: Events include a monitor snapshot in data.monitor. The monitor.changes.detected and monitor.run.completed events always include data.run, with the same run object returned by Get a run.
This event contains one Search finding. Page findings use the same event envelope.
When an event includes a run, it contains the complete run without dropping changes. A Page change’s diff.truncated refers only to its diff text, not to the event body. For an automatic pause, data.monitor.pause_reason identifies the cause. The data.run field is optional; when present, it contains the run that caused the pause. A notification to an unhealthy receiver can fail, so inspect the monitor directly rather than waiting for that event.

Verify signatures

Deliveries use Standard Webhooks v1 and include three headers. Verify the signature before processing the event: In this notation, <webhook-id> and <webhook-timestamp> are the received header values. The + means byte concatenation.
Compute HMAC-SHA256 over signed_payload using signing_key, then base64-encode the digest. Compare it in constant time with the supplied v1 signatures, and accept a matching signature only if the timestamp is within five minutes of your clock. Use the original request body bytes, before parsing or reserializing JSON. Deduplicate events by webhook-id, which equals the event body’s id, and changes by data.run.changes[].id. Delivery is at least once, and events can arrive out of order.

Delivery and retries

Return any 2xx response within ten seconds, then process the event asynchronously. The response body is ignored, and redirects are not followed. Delivery errors do not change a completed run’s status. Persistent failures can automatically pause the monitor.

Update or remove a webhook

Use Update a monitor to attach a webhook or replace its URL and event subscriptions. Omitted or empty events selects the default subscriptions. Include your desired event list when updating a webhook to preserve nondefault subscriptions. To remove notifications while keeping the monitor running, send:
cURL

Test delivery

Send one signed test event to the configured receiver:
cURL
The response contains event_id, delivered, and duration_ms, with status_code or error when available. Check delivered even if the HTTP response is 200. The monitor.webhook.test event contains data.monitor and no data.run; it creates no run and is not retried. You can test a paused monitor. A monitor without a webhook returns 409 invalid_state; configure a webhook before testing delivery.

Pricing and limits

See Monitor API pricing for rates and billable units. Use the pricing calculator to estimate costs for your usage. See Monitor API limits for HTTP request tiers, active-monitor limits, and retry guidance. Polling and lifecycle operations share the HTTP request budget.

Examples

Track competitor news

Create a daily Search monitor for product launches and business news.

Track API and pricing changes

Watch a changelog, pricing page, and API guide with a Page monitor.