> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Schedule web searches or page checks, read saved results, and manage your monitors.

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](https://console.perplexity.ai/project/monitors).

## Choose a monitor type

> [card] [Search](https://docs.perplexity.ai/docs/monitors/search-monitoring.md)
>
> Find relevant web results over time.

> [card] [Page](https://docs.perplexity.ai/docs/monitors/page-monitoring.md)
>
> 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](https://docs.perplexity.ai/docs/monitors/search-monitoring.md#freshness) and [Page comparisons](https://docs.perplexity.ai/docs/monitors/page-monitoring.md#read-page-changes).

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](#webhook-notifications) for notifications.

## Quickstart

Create a Search monitor and read its first results. To track changes at known URLs instead, follow the [Page quickstart](https://docs.perplexity.ai/docs/monitors/page-monitoring.md#create-a-page-monitor).

You need cURL, jq, and a Perplexity [API key](https://docs.perplexity.ai/docs/admin/api-key-management.md). Set the key in your environment:

```bash theme={null}
export PERPLEXITY_API_KEY="YOUR_API_KEY"
```

### Create a monitor

This request creates a Search monitor and returns its configuration. To read the results, use the [Check results](#check-results) request below.

```bash cURL theme={null}
curl --request POST https://api.perplexity.ai/v1/monitors \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "AI research and product news",
    "targets": [
      {
        "type": "search",
        "query": "AI product launches and research news",
        "max_results": 3
      }
    ],
    "schedule": {"type": "interval", "interval": "1w"}
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "created_at": "2026-11-13T12:33:28Z",
>   "goal": "",
>   "id": "mon_01M7AEC2JDKJECVTX0VZRJXPBT",
>   "metadata": {},
>   "name": "AI research and product news",
>   "next_run_at": "2026-11-13T12:33:28Z",
>   "object": "monitor",
>   "schedule": {
>     "interval": "1w",
>     "type": "interval"
>   },
>   "status": "active",
>   "targets": [
>     {
>       "filters": {
>         "exclude_domains": [],
>         "freshness": ["published", "updated"],
>         "include_domains": []
>       },
>       "max_results": 3,
>       "query": "AI product launches and research news",
>       "type": "search"
>     }
>   ],
>   "updated_at": "2026-11-13T12:33:28Z"
> }
> ```

Set `MONITOR_ID` to the returned `id`:

```bash theme={null}
export MONITOR_ID="mon_REPLACE_WITH_YOUR_MONITOR_ID"
```

### Check results

Read the latest run:

```bash cURL theme={null}
curl "https://api.perplexity.ai/v1/monitors/$MONITOR_ID/runs?limit=1" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "changes": [
>         {
>           "confidence": 0.9656780315254148,
>           "id": "chg_40620bb6f8590d2750dccd53da399368",
>           "last_updated_at": "2026-11-13T00:00:00Z",
>           "published_at": "2026-11-12T00:00:00Z",
>           "snippet": "IBM Newsroom - Latest News # Artificial intelligence news - IBM advances agent identity security with new Vault capabilities With the acquisition of AuthMind, IBM is expanding HashiCorp Vault’s approach to securing the agent lifecycle, helping organizations protect credentials and secrets not only when they are... November 12, 2026 - IBM Announces Winner of Sports Tech Startup Prize Challenge at Web Summit Lisbon 2026 IBM (NYSE: IBM) today announced LivXP as the winner of the IBM Sports Tech…",
>           "title": "Artificial intelligence news",
>           "type": "search_result",
>           "url": "https://newsroom.ibm.com/latest-news-artificial-intelligence?apiversion=v2\u0026domshim=1\u0026noservercache=1\u0026noservertelemetry=1\u0026batchservertelemetry=1\u0026renderwebcomponents=1\u0026l=50"
>         },
>         {
>           "confidence": 0.8460792033429543,
>           "id": "chg_85bda43aed3f7c560d09e10ba29c540b",
>           "last_updated_at": "2026-11-13T00:00:00Z",
>           "published_at": "2026-11-10T00:00:00Z",
>           "snippet": "Future Tools - AI News # Latest AI News The most comprehensive AI news feed on the internet -- curated by Matt Wolfe *News may update slower on weekends and when Matt's traveling Get This In Your Inbox Twice a Week The Twice-Weekly AI Briefing Join 250,000+ readers getting the most important AI news and tools every Wednesday and Friday. Free forever. Matt's picksPaywalled Nov 7 – 13, 2026 ## Yesterday — Thursday, November 12, 2026 Nvidia Ex-CEO Jensen Huang Had 3rd Employee Affair; Stock Down…",
>           "title": "AI News",
>           "type": "search_result",
>           "url": "https://futuretools.io/news"
>         },
>         {
>           "confidence": 0.8438822548246814,
>           "id": "chg_f6afbe93aefdf7925677840000b3ebbb",
>           "last_updated_at": "2026-11-12T00:00:00Z",
>           "published_at": "2026-11-11T00:00:00Z",
>           "snippet": "# A Eye on AI A Eye on AI - 0.0 (0) - Tech News - Daily A Eye on AI is a fast-moving briefing on how artificial intelligence is reshaping the world — not for engineers or AI insiders, but for the professionals, business leaders, and everyday people navigating its effects. Each episode tracks the latest developments through three lenses: international relations and trade, business and industry, and everyday life — always asking not just what happened, but who it affects and why it matters.…",
>           "title": "A Eye on AI",
>           "type": "search_result",
>           "url": "https://podcasts.apple.com/us/podcast/a-eye-on-ai/id6799575515"
>         }
>       ],
>       "counts": {
>         "candidates": 3,
>         "changes": 3,
>         "errors": 0
>       },
>       "created_at": "2026-11-13T12:33:35Z",
>       "finished_at": "2026-11-13T12:33:37Z",
>       "id": "run_01M7AEC9MBX7356DQ0XJ9EEHDJ",
>       "monitor_id": "mon_01M7AEC2JDKJECVTX0VZRJXPBT",
>       "object": "monitor.run",
>       "status": "succeeded",
>       "target_errors": [],
>       "trigger": "schedule",
>       "window": {
>         "from": "2026-11-06T12:33:28Z",
>         "to": "2026-11-13T12:33:35Z"
>       }
>     }
>   ],
>   "has_more": false,
>   "object": "list"
> }
> ```

[Pause the monitor](#pause-and-resume) when you finish trying it. The [Search guide](https://docs.perplexity.ai/docs/monitors/search-monitoring.md) covers filters and query options; the [Page guide](https://docs.perplexity.ai/docs/monitors/page-monitoring.md) covers known URLs and text changes.

## Run status and history

| Run status | Meaning |
| - | - |
| `queued` | Accepted but not yet executing; `window` is omitted. |
| `running` | Execution is in progress. |
| `succeeded` | Finished, possibly with no changes or with individual target errors. |
| `failed` | Execution failed. Inspect `error.code`, `error.message`, and `target_errors`. |
| `skipped` | The run did not complete, for example because a queued run was cancelled when the monitor was paused. |

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:

```bash cURL theme={null}
curl --request PATCH "https://api.perplexity.ai/v1/monitors/$MONITOR_ID" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "schedule": {"type": "interval", "interval": "1d"}
  }' | jq
```

### 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:

```bash cURL theme={null}
curl --request POST "https://api.perplexity.ai/v1/monitors/$MONITOR_ID/run" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "id": "run_02",
>   "object": "monitor.run",
>   "monitor_id": "mon_01M7AEC2JDKJECVTX0VZRJXPBT",
>   "trigger": "manual",
>   "status": "queued",
>   "counts": {
>     "candidates": 0,
>     "changes": 0,
>     "errors": 0
>   },
>   "usage": {
>     "searches": 0,
>     "fetched_urls": 0,
>     "cost": {
>       "total_cost": 0,
>       "currency": "USD"
>     }
>   },
>   "changes": [],
>   "target_errors": [],
>   "created_at": "2026-11-13T12:35:00Z"
> }
> ```

Use the returned run `id` with [Get a run](https://docs.perplexity.ai/api-reference/monitors-run-get.md). 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:

```bash cURL theme={null}
curl --request PATCH "https://api.perplexity.ai/v1/monitors/$MONITOR_ID" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"goal": "Product releases and availability changes; ignore cosmetic edits."}' | jq
```

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](https://docs.perplexity.ai/docs/monitors/search-monitoring.md#queries-and-goals) or [Page judging](https://docs.perplexity.ai/docs/monitors/page-monitoring.md#set-a-relevance-goal) for how each type uses the goal.

## Manage monitors

Retrieve the monitor to check its configuration and status:

```bash cURL theme={null}
curl "https://api.perplexity.ai/v1/monitors/$MONITOR_ID" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "created_at": "2026-11-13T12:33:28Z",
>   "goal": "",
>   "id": "mon_01M7AEC2JDKJECVTX0VZRJXPBT",
>   "last_run": {
>     "change_count": 3,
>     "finished_at": "2026-11-13T12:33:37Z",
>     "id": "run_01M7AEC9MBX7356DQ0XJ9EEHDJ",
>     "status": "succeeded"
>   },
>   "metadata": {},
>   "name": "AI research and product news",
>   "next_run_at": "2026-11-21T01:37:24Z",
>   "object": "monitor",
>   "schedule": {
>     "interval": "1w",
>     "type": "interval"
>   },
>   "status": "active",
>   "targets": [
>     {
>       "filters": {
>         "exclude_domains": [],
>         "freshness": ["published", "updated"],
>         "include_domains": []
>       },
>       "max_results": 3,
>       "query": "AI product launches and research news",
>       "type": "search"
>     }
>   ],
>   "updated_at": "2026-11-13T12:33:37Z"
> }
> ```

Use `PATCH` to update a monitor. See [Update a monitor](https://docs.perplexity.ai/api-reference/monitors-update-patch.md) 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.

```bash cURL theme={null}
curl --request POST "https://api.perplexity.ai/v1/monitors/$MONITOR_ID/pause" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" | jq
```

Resume a paused monitor after resolving any [automatic-pause cause](#automatic-pausing). If you paused it manually, resume it when you want scheduled runs to start again.

```bash cURL theme={null}
curl --request POST "https://api.perplexity.ai/v1/monitors/$MONITOR_ID/resume" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" | jq
```

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:

```bash cURL theme={null}
curl --request DELETE "https://api.perplexity.ai/v1/monitors/$MONITOR_ID" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" | jq
```

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.

| HTTP status | Meaning and next step |
| - | - |
| `400` | Invalid field or request shape. Correct the request before retrying. |
| `402` | Insufficient credits for the requested operation. Check billing before retrying. |
| `403` | Organization policy does not allow the operation. Organizations requiring zero data retention cannot create, resume, or run monitors. |
| `404` | Monitor or run not found in your API organization. Check the IDs and API key. |
| `409` | For `invalid_state`, change the monitor's state or configuration before retrying. For `conflict`, retry the concurrent update. For `run_in_progress`, follow `current_run_id`. For `quota_exceeded`, pause or delete an active monitor; see [active monitor limits](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md#active-monitor-limits). |
| `429` | HTTP request limit exceeded. Wait for `Retry-After`; see [Monitor API limits](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md#monitor-api-limits). |
| `502`, `503`, `504` | Service failure, unavailability, or timeout. Back off; use the same idempotency key when retrying creation. |

## 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.

| Pause reason | What happened | What to do |
| - | - | - |
| `webhook_failing` | Webhook delivery failures reached the service's pause threshold. | Fix the receiver so it returns `2xx` within ten seconds, update the webhook, or remove it. |
| `source_failing` | Repeated runs could not read their sources. | Inspect the run error and `target_errors`. Resolve the source failures or update the targets before resuming. |
| `insufficient_credits` | A credit check denied a run. | Add credits, then resume the monitor explicitly. |
| `org_policy` | Your organization's policy no longer permits execution. | Confirm that the organization's policy permits monitoring before resuming. |

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](#pause-and-resume) 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:

```bash cURL theme={null}
curl --request PATCH "https://api.perplexity.ai/v1/monitors/$MONITOR_ID" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "webhook": {"url": "https://example.com/webhooks/perplexity"}
  }' | jq
```

When you attach a webhook without a supplied secret, the response includes a one-time signing secret:

```json theme={null}
{
  "webhook": {
    "url": "https://example.com/webhooks/perplexity",
    "secret": "whsec_REPLACE_WITH_YOUR_CREATION_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](#update-or-remove-a-webhook) 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:

| Event | When it is sent |
| - | - |
| `monitor.changes.detected` | A run succeeds with at least one change. |
| `monitor.run.completed` | A run succeeds, with or without changes, or fails. Subscribe explicitly to receive it; skipped runs do not send it. |
| `monitor.paused` | The service automatically pauses the monitor. A manual pause does not send it. |

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](https://docs.perplexity.ai/api-reference/monitors-run-get.md).

> [accordion] Example event
>
> This event contains one Search finding. Page findings use the same event envelope.
>
> ```json theme={null}
> {
>   "id": "evt_0123456789abcdef0123456789abcdef",
>   "object": "event",
>   "type": "monitor.changes.detected",
>   "timestamp": "2026-11-10T09:00:30Z",
>   "data": {
>     "monitor": {
>       "id": "mon_01",
>       "name": "Battery recycling research",
>       "status": "active",
>       "metadata": {}
>     },
>     "run": {
>       "id": "run_01",
>       "object": "monitor.run",
>       "monitor_id": "mon_01",
>       "trigger": "schedule",
>       "status": "succeeded",
>       "window": {
>         "from": "2026-11-09T09:00:00Z",
>         "to": "2026-11-10T09:00:00Z"
>       },
>       "counts": {"candidates": 1, "changes": 1, "errors": 0},
>       "usage": {
>         "searches": 1,
>         "fetched_urls": 0,
>         "cost": {"total_cost": 0.001, "currency": "USD"}
>       },
>       "changes": [
>         {
>           "id": "chg_0123456789abcdef0123456789abcdef",
>           "type": "search_result",
>           "url": "https://example.com/research/battery-recycling",
>           "title": "A new battery recycling process",
>           "confidence": 0.91
>         }
>       ],
>       "target_errors": [],
>       "created_at": "2026-11-10T09:00:00Z",
>       "finished_at": "2026-11-10T09:00:30Z"
>     }
>   }
> }
> ```

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](#automatic-pausing), `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:

| Header | Meaning |
| - | - |
| `webhook-id` | Delivery ID, unchanged across retries of that delivery. |
| `webhook-timestamp` | Unix seconds when this attempt was signed. |
| `webhook-signature` | One or more space-separated entries, each `v1,` followed by a base64 signature. |

In this notation, `<webhook-id>` and `<webhook-timestamp>` are the received header values. The `+` means byte concatenation.

```text theme={null}
signing_key = base64_decode(secret without "whsec_" prefix)
signed_payload = <webhook-id> + "." + <webhook-timestamp> + "." + <raw request body>
```

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.

| Receiver result | Delivery behavior |
| - | - |
| Timeout, network error, `408`, `429`, or `5xx` | Retry after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, and 10 hours: seven attempts over about 17.6 hours. |
| `3xx`, `410`, other `4xx`, or TLS certificate failure | End the delivery without further retries. |

Delivery errors do not change a completed run's status. Persistent failures can [automatically pause](#automatic-pausing) the monitor.

### Update or remove a webhook

Use [Update a monitor](https://docs.perplexity.ai/api-reference/monitors-update-patch.md) 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:

```bash cURL theme={null}
curl --request PATCH "https://api.perplexity.ai/v1/monitors/$MONITOR_ID" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"webhook": null}' | jq
```

### Test delivery

Send one signed test event to the configured receiver:

```bash cURL theme={null}
curl --request POST "https://api.perplexity.ai/v1/monitors/$MONITOR_ID/webhook/test" \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" | jq
```

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](https://docs.perplexity.ai/docs/getting-started/pricing.md#monitor-api-pricing) for rates and billable units. Use the [pricing calculator](https://docs.perplexity.ai/docs/getting-started/pricing.md?calc=monitor#estimate-your-cost) to estimate costs for your usage.

See [Monitor API limits](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md#monitor-api-limits) for HTTP request tiers, active-monitor limits, and retry guidance. Polling and lifecycle operations share the HTTP request budget.

## Examples

> [card] [Track competitor news](https://docs.perplexity.ai/docs/cookbook/articles/search-monitor-news/README.md)
>
> Create a daily Search monitor for product launches and business news.

> [card] [Track API and pricing changes](https://docs.perplexity.ai/docs/cookbook/articles/page-monitor-changelog/README.md)
>
> Watch a changelog, pricing page, and API guide with a Page monitor.
