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

# Search

> Run a search on a schedule and read new, relevant results through the API.

A Search monitor runs a query on a schedule and saves new, relevant results. Use it to follow a topic across the web; use [Page monitoring](https://docs.perplexity.ai/docs/monitors/page-monitoring.md) to track later edits at known URLs.

## Create a Search monitor

Use cURL and jq, and set `PERPLEXITY_API_KEY` to your [API key](https://docs.perplexity.ai/docs/admin/api-key-management.md). Creating a monitor makes its first run due immediately and schedules later runs until you [pause or delete it](https://docs.perplexity.ai/docs/monitors/overview.md#pause-and-resume); see [Monitor API pricing](https://docs.perplexity.ai/docs/getting-started/pricing.md#monitor-api-pricing).

```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
```

The `200` response is a monitor, not a completed run. Set `MONITOR_ID` to its `id` for the requests below.

Use an [idempotency key](https://docs.perplexity.ai/api-reference/monitors-create-post.md#webhook-secrets-and-retries) if your application retries creation.

> [!NOTE]
>
> This example reads results through the API without configuring a webhook. Use [webhooks](https://docs.perplexity.ai/docs/monitors/overview.md#webhook-notifications) to receive change notifications without polling for results.

## Read the results

A run is one execution of a monitor. Its `changes` array contains the Search results it kept. Retrieve the latest run using `MONITOR_ID`; the first run starts asynchronously after creation, so do not submit another `/run` request for it.

The two responses below show the same run. Use the IDs returned by your own requests.

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

> [accordion] List runs 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"
> }
> ```

If the list is empty, read it again later. For `queued`, `running`, or an unknown status, keep polling with a bounded retry policy. For `failed` or `skipped`, inspect `error`; a `succeeded` run can have an empty `changes` array.

Set `RUN_ID` to the run ID in `data[0].id`, then retrieve that run. Run history is retained for 90 days.

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

> [accordion] Get run response
>
> ```json theme={null}
> {
>   "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"
>   }
> }
> ```

Each result includes a URL and a confidence score.

Every run includes [usage and cost](https://docs.perplexity.ai/api-reference/monitors-run-get.md). Check `usage.searches` in the run response for the count.

## Configure your search

Put one target with `type: "search"` in `targets`.

| Parameter | Type | Default | Constraints |
| - | - | - | - |
| `targets[0].query` | string | None | Required, nonempty, up to 1,000 characters. |
| `targets[0].max_results` | integer | `20` | Maximum search results considered per query, from `1` to `20`. The run can keep fewer. |
| `targets[0].filters.freshness` | array of strings | `["published", "updated"]` | Choose which source dates qualify candidates. Omitted or `[]` selects both. |
| `targets[0].filters.include_domains` | array of strings | Unrestricted | Up to 20 bare host names to include. Omitted or `[]` leaves domains unrestricted. |
| `targets[0].filters.exclude_domains` | array of strings | None | Up to 20 bare host names to exclude. Omitted or `[]` excludes none. |

### Queries and goals

The query supplies the topic, and an optional `goal` describes which results to keep. Judging checks source legitimacy, whether the result adds new information, and whether it fits the run's [time window](#freshness). When you provide a goal, it also checks relevance to your instructions.

### Freshness

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.

The monitor uses its schedule and prior successful run to set a run window. Before the first successful run, the window starts one schedule period before creation, up to seven days earlier. Later windows normally start where the last successful window ended, subject to the service's lookback limit. The window ends when the run starts.

### Domain filters

Supply bare host names such as `example.com`, without a scheme, path, or port. Each entry also covers its subdomains.

### Deduplication and results

Search monitors deduplicate normalized URLs, both within a run and against previously seen URLs. Changing the goal does not replay seen URLs. Selecting `updated` freshness still deduplicates known URLs; use Page monitoring to watch for later edits at a known URL.

Seen-URL state is retained for 90 days and refreshed when a URL is encountered again. You can [update the query](#update-your-search) while keeping that history, or create a new monitor for fresh discovery history.

### Update your search

Replace the Search target to change the query and restrict its sources:

```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 '{
    "targets": [
      {
        "type": "search",
        "query": "new AI model releases",
        "max_results": 3,
        "filters": {
          "freshness": ["published", "updated"],
          "include_domains": ["example.com"],
          "exclude_domains": ["blog.example.com"]
        }
      }
    ]
  }' | jq
```

Repeat the target's required fields and any nondefault options you want to keep. Omitting `max_results` resets it to `20`. Without `filters`, both freshness modes apply and domain restrictions are removed; omitting an individual filter resets that filter to its default. An empty or `null` `targets` value is invalid.

You can [update the goal](https://docs.perplexity.ai/docs/monitors/overview.md#goals-and-judging) separately without replacing the target. Deduplication still applies, so changing the goal does not replay seen URLs.

## Next steps

[Pause the monitor](https://docs.perplexity.ai/docs/monitors/overview.md#pause-and-resume) when you finish trying it. You can also [change its schedule](https://docs.perplexity.ai/docs/monitors/overview.md#schedules), [add webhooks](https://docs.perplexity.ai/docs/monitors/overview.md#webhook-notifications), or check the [API reference](https://docs.perplexity.ai/api-reference/monitors-create-post.md) for the full contract.

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