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

# Create a monitor

> Create an active Search or Page monitor.

Use exactly one Search target, or 1 to 10 Page targets with distinct URLs. Do not mix Search and Page targets in one monitor. The monitor starts as `active`; its first run becomes due immediately and starts asynchronously.

`goal` is optional and separate from the Search query. To retrieve results without notifications, omit `webhook` or set it to `null`; runs and their `changes` remain available through the API.

## Webhook secrets and retries

When you configure a webhook without a `secret`, the service generates one and returns it in `webhook.secret` only in the response that generated it. Store it to verify deliveries. A secret you supply is never returned.

Use an `Idempotency-Key` header when retrying the original create request. Reusing the key returns the original monitor in its current state, even after an update, without its secret. Using the same key for a different create request returns `400`. If the first response was lost, set a new secret with [Update a monitor](https://docs.perplexity.ai/api-reference/monitors-update-patch.md).

Creating a monitor at your API organization's active-monitor cap returns HTTP `409` with `quota_exceeded`. Pause or delete an active monitor, or upgrade the organization's tier, before retrying.

```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": "Battery recycling research",
    "targets": [
      {
        "type": "search",
        "query": "battery recycling research",
        "max_results": 3
      }
    ],
    "schedule": {"type": "interval", "interval": "1d"}
  }' | jq
```


## OpenAPI

````yaml post /v1/monitors
openapi: 3.1.0
info:
  title: Perplexity AI API
  description: Perplexity AI API
  version: 1.0.0
servers:
  - url: https://api.perplexity.ai
    description: Perplexity AI API
security: []
paths:
  /v1/monitors:
    post:
      tags:
        - Monitors
      summary: Create a monitor
      description: >-
        Creates an `active` monitor. Its first run is due immediately and starts
        asynchronously; retrieve results with Get a run or List a monitor's
        runs.


        Omit `webhook` or set it to null to retrieve results without
        notifications. If you configure a webhook without a `secret`, this
        response returns the generated secret in `webhook.secret`. Store it to
        verify deliveries. A secret you supply is never returned.


        Use `Idempotency-Key` for retries. The same key and body return the
        original monitor in its current state, without its secret. Reusing the
        key with a different body returns `400`. If the first response was lost,
        set a new secret with Update a monitor.


        Active-monitor limits apply per API organization: 100 for tiers 0 and 1,
        200 for tier 2, 300 for tier 3, 400 for tier 4, and 500 for tier 5.
        Paused monitors do not count. Creating or resuming at the limit returns
        HTTP `409` with `quota_exceeded`. Pause or delete an active monitor, or
        upgrade the organization's tier, before retrying.
      operationId: createMonitor
      parameters:
        - $ref: '#/components/parameters/MonitorIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMonitorRequest'
            examples:
              search:
                summary: Search monitor on an interval schedule
                value:
                  name: Acme launches
                  goal: >-
                    Alert on new product launches or price changes. Ignore
                    opinion pieces.
                  targets:
                    - type: search
                      query: Acme Corp product launch
                      max_results: 20
                      filters:
                        freshness:
                          - published
                          - updated
                        include_domains:
                          - techcrunch.com
                          - theverge.com
                  schedule:
                    type: interval
                    interval: 1d
                  webhook:
                    url: https://example.com/hooks/perplexity
                    events:
                      - monitor.changes.detected
                      - monitor.paused
                  metadata:
                    customer_user: u_123
              own_secret:
                summary: Search monitor with your own webhook secret and every event
                value:
                  name: Acme launches
                  targets:
                    - type: search
                      query: Acme Corp product launch
                  schedule:
                    type: interval
                    interval: 1d
                  webhook:
                    url: https://example.com/hooks/perplexity
                    events:
                      - monitor.changes.detected
                      - monitor.run.completed
                      - monitor.paused
                    secret: whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
              page:
                summary: Page monitor without a webhook
                value:
                  name: Acme pricing
                  targets:
                    - type: page
                      url: https://acme.com/pricing
                    - type: page
                      url: https://acme.com/changelog
                  schedule:
                    type: interval
                    interval: 6h
      responses:
        '200':
          description: >-
            The created monitor, with `webhook.secret` if the service generated
            it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
              example:
                id: mon_01JC8ZK3Q4V5W6X7Y8Z9A0B1C2
                object: monitor
                name: Acme launches
                goal: >-
                  Alert on new product launches or price changes. Ignore opinion
                  pieces.
                targets:
                  - type: search
                    query: Acme Corp product launch
                    max_results: 20
                    filters:
                      freshness:
                        - published
                        - updated
                      include_domains:
                        - techcrunch.com
                        - theverge.com
                      exclude_domains: []
                schedule:
                  type: interval
                  interval: 1d
                webhook:
                  url: https://example.com/hooks/perplexity
                  events:
                    - monitor.changes.detected
                    - monitor.paused
                  secret: whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
                metadata:
                  customer_user: u_123
                status: active
                next_run_at: '2026-11-12T10:00:00Z'
                created_at: '2026-11-12T10:00:00Z'
                updated_at: '2026-11-12T10:00:00Z'
        '400':
          $ref: '#/components/responses/MonitorBadRequest'
        '401':
          $ref: '#/components/responses/MonitorUnauthorized'
        '402':
          $ref: '#/components/responses/MonitorPaymentRequired'
        '403':
          $ref: '#/components/responses/MonitorForbidden'
        '409':
          description: |
            Organization active-monitor cap reached (`quota_exceeded`).
            Pause or delete an active monitor, or upgrade the organization's
            tier, before retrying. Paused monitors do not count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorApiError'
        '429':
          $ref: '#/components/responses/MonitorTooManyRequests'
        '502':
          $ref: '#/components/responses/MonitorBadGateway'
        '503':
          $ref: '#/components/responses/MonitorUnavailable'
        '504':
          $ref: '#/components/responses/MonitorGatewayTimeout'
      security:
        - HTTPBearer: []
      servers:
        - url: https://api.perplexity.ai
          description: Production API
components:
  parameters:
    MonitorIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 200
      description: >-
        Unique key for this create. A repeat with the same key and the same body
        returns the monitor that the first request created, in its current state
        and without the secret; the same key with a different body is a 400.
  schemas:
    CreateMonitorRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - targets
        - schedule
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
        goal:
          type: string
          maxLength: 2000
          description: What counts as worth an alert; each candidate is judged against it
        targets:
          $ref: '#/components/schemas/MonitorTargets'
        schedule:
          $ref: '#/components/schemas/MonitorScheduleRequest'
        webhook:
          anyOf:
            - type: object
              allOf:
                - $ref: '#/components/schemas/MonitorWebhookRequest'
              description: Optional delivery endpoint; omitted or null sends no events
            - type: 'null'
        metadata:
          $ref: '#/components/schemas/MonitorMetadata'
    Monitor:
      type: object
      description: |
        Fields that do not apply are omitted, never null: `webhook`,
        `pause_reason`, `current_run_id`, `next_run_at` and `last_run`.
      required:
        - id
        - object
        - name
        - goal
        - targets
        - schedule
        - metadata
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          maxLength: 64
          description: Opaque ID with the prefix `mon_`
        object:
          type: string
          enum:
            - monitor
        name:
          type: string
        goal:
          type: string
          description: '`""` when unset'
        targets:
          type: array
          items:
            $ref: '#/components/schemas/MonitorTarget'
        schedule:
          $ref: '#/components/schemas/MonitorSchedule'
        webhook:
          $ref: '#/components/schemas/MonitorWebhook'
        metadata:
          $ref: '#/components/schemas/MonitorMetadata'
        status:
          $ref: '#/components/schemas/MonitorStatus'
        pause_reason:
          allOf:
            - $ref: '#/components/schemas/MonitorPauseReason'
          description: Only while `paused`
        current_run_id:
          type: string
          description: The queued or running run
        next_run_at:
          allOf:
            - $ref: '#/components/schemas/MonitorTimestamp'
          description: Omitted while paused
        last_run:
          $ref: '#/components/schemas/MonitorLastRun'
        created_at:
          $ref: '#/components/schemas/MonitorTimestamp'
        updated_at:
          $ref: '#/components/schemas/MonitorTimestamp'
    MonitorApiError:
      type: object
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
          properties:
            message:
              description: Human-readable error message
              type: string
            type:
              $ref: '#/components/schemas/MonitorApiErrorType'
            code:
              type: integer
              description: HTTP status code
            param:
              type: string
              description: Parameter that caused the error
    MonitorTargets:
      type: array
      minItems: 1
      maxItems: 10
      items:
        $ref: '#/components/schemas/MonitorTargetRequest'
      description: >-
        Exactly one `search` target, or 1 to 10 `page` targets with distinct
        URLs
    MonitorScheduleRequest:
      oneOf:
        - $ref: '#/components/schemas/MonitorIntervalScheduleRequest'
        - $ref: '#/components/schemas/MonitorCronScheduleRequest'
      discriminator:
        propertyName: type
        mapping:
          interval: '#/components/schemas/MonitorIntervalScheduleRequest'
          cron: '#/components/schemas/MonitorCronScheduleRequest'
    MonitorWebhookRequest:
      anyOf:
        - type: object
          additionalProperties: false
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              maxLength: 2048
              description: HTTPS endpoint with a public address
            events:
              type: array
              uniqueItems: true
              items:
                $ref: '#/components/schemas/MonitorEventType'
              description: |
                Event types to send. Omitted or empty means
                `[monitor.changes.detected, monitor.paused]`. An unknown type
                returns 400 with param `webhook.events[N]`, the index of the
                first unknown entry.
            secret:
              allOf:
                - $ref: '#/components/schemas/MonitorWebhookSecret'
              description: >
                Optional signing secret. Without it, create generates one and an

                update keeps the current one (or generates one when the monitor

                had no webhook). A different secret on update rotates: the old
                one

                also signs for 24 hours. A secret you send is never returned.
        - type: 'null'
    MonitorMetadata:
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 512
      description: >-
        Up to 16 key value pairs; keys 1 to 64 characters, values up to 512
        characters (Unicode code points, valid UTF-8). Echoed on every webhook.
    MonitorTarget:
      description: |
        One thing a monitor watches. Today a monitor has exactly one `search`
        target, or 1 to 10 `page` targets with distinct URLs. New types may
        be added; skip targets with an unknown type.
      oneOf:
        - $ref: '#/components/schemas/MonitorSearchTarget'
        - $ref: '#/components/schemas/MonitorPageTarget'
      discriminator:
        propertyName: type
        mapping:
          search: '#/components/schemas/MonitorSearchTarget'
          page: '#/components/schemas/MonitorPageTarget'
    MonitorSchedule:
      description: When a monitor runs. New types may be added.
      oneOf:
        - $ref: '#/components/schemas/MonitorIntervalSchedule'
        - $ref: '#/components/schemas/MonitorCronSchedule'
      discriminator:
        propertyName: type
        mapping:
          interval: '#/components/schemas/MonitorIntervalSchedule'
          cron: '#/components/schemas/MonitorCronSchedule'
    MonitorWebhook:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
        events:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/MonitorEventType'
          description: The subscribed event types, defaults filled in
        secret:
          allOf:
            - $ref: '#/components/schemas/MonitorWebhookSecret'
          description: |
            Present only in the response that generated it: a create, or an
            update that adds a webhook, without a `secret` in the request.
    MonitorStatus:
      type: string
      enum:
        - active
        - paused
      description: |
        `active` monitors run on their schedule; `paused` ones don't run until
        resumed. Whether a run is in flight is `current_run_id`, not the
        status. New statuses may be added; treat an unknown one as not
        running on its schedule.
    MonitorPauseReason:
      type: string
      enum:
        - user
        - insufficient_credits
        - org_policy
        - webhook_failing
        - source_failing
      description: >
        Why a `paused` monitor stopped: you paused it (`user`), credits ran

        out, webhook deliveries repeatedly failed (`webhook_failing`), every
        source the monitor reads repeatedly failed (`source_failing`), or your
        API Group's policy

        no longer allows monitors. Resume it once the cause is

        fixed. New reasons may be added; treat an unknown value as a reason to

        check the monitor before resuming it.
    MonitorTimestamp:
      type: string
      format: date-time
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
      description: RFC 3339 in UTC with whole seconds, for example `2026-11-12T09:00:41Z`.
    MonitorLastRun:
      type: object
      description: The last finished run
      required:
        - id
        - status
        - change_count
        - finished_at
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/MonitorRunStatus'
        change_count:
          type: integer
          format: int32
        finished_at:
          $ref: '#/components/schemas/MonitorTimestamp'
    MonitorApiErrorType:
      type: string
      enum:
        - invalid_request
        - invalid_api_key
        - token_expired
        - insufficient_quota
        - payment_required
        - forbidden
        - api_product_not_allowed
        - not_found
        - invalid_state
        - conflict
        - quota_exceeded
        - run_in_progress
        - request_rate_limit_exceeded
        - internal_error
        - bad_gateway
        - service_unavailable
        - gateway_timeout
      description: >
        Machine-readable error type. Monitors returns `invalid_request`

        (400), `invalid_api_key`, `token_expired` and

        `insufficient_quota` (401), `payment_required` (402),

        `forbidden` and `api_product_not_allowed` (403), `not_found`

        (404), `invalid_state` (409: the monitor's state does not allow

        the request; change it first), `conflict` (409: the monitor was

        modified concurrently; retry), `quota_exceeded` (409),

        `run_in_progress` (409), `request_rate_limit_exceeded` (429),

        `internal_error` (500), `bad_gateway` (502), `service_unavailable` (503)
        and

        `gateway_timeout` (504). New types may be added; act on `code`

        for an unknown one.
    MonitorTargetRequest:
      oneOf:
        - $ref: '#/components/schemas/MonitorSearchTargetRequest'
        - $ref: '#/components/schemas/MonitorPageTargetRequest'
      discriminator:
        propertyName: type
        mapping:
          search: '#/components/schemas/MonitorSearchTargetRequest'
          page: '#/components/schemas/MonitorPageTargetRequest'
    MonitorIntervalScheduleRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - interval
      properties:
        type:
          type: string
          enum:
            - interval
        interval:
          type: string
          pattern: ^[1-9][0-9]*[mhdw]$
          description: |
            A whole number of minutes, hours, days or weeks (`30m`, `6h`,
            `1d`, `2w`), from `1m` to `31d`. Runs get up to 10% jitter.
    MonitorCronScheduleRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - cron
      properties:
        type:
          type: string
          enum:
            - cron
        cron:
          type: string
          maxLength: 128
        timezone:
          type: string
          default: UTC
    MonitorEventType:
      type: string
      enum:
        - monitor.changes.detected
        - monitor.run.completed
        - monitor.paused
      description: |
        `monitor.changes.detected`: a run succeeded with at least one change.
        `monitor.run.completed`: a run ended `succeeded` (with or without
        changes) or `failed`. `monitor.paused`: the service paused the
        monitor; your own pause sends nothing. New types may be added; a new
        type is sent only to webhooks that list it in `events`.
    MonitorWebhookSecret:
      type: string
      minLength: 38
      maxLength: 94
      pattern: ^whsec_(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
      description: |
        Standard Webhooks signing secret: `whsec_` plus the standard (padded)
        base64 of 24 to 64 bytes; the HMAC key is the decoded bytes.
    MonitorSearchTarget:
      type: object
      description: Reports pages new to `query` since the last run.
      required:
        - type
        - query
        - max_results
        - filters
      properties:
        type:
          type: string
          enum:
            - search
        query:
          type: string
        max_results:
          type: integer
          format: int32
          minimum: 1
          maximum: 20
          description: Maximum search results considered per query; the run can keep fewer.
        filters:
          $ref: '#/components/schemas/MonitorSearchFilters'
    MonitorPageTarget:
      type: object
      description: |
        Reports meaningful changes to one URL. The first run of a page
        target saves a baseline and reports nothing.
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum:
            - page
        url:
          type: string
          maxLength: 2048
          description: Absolute `http(s)` URL of a public host, without credentials
    MonitorIntervalSchedule:
      type: object
      required:
        - type
        - interval
      properties:
        type:
          type: string
          enum:
            - interval
        interval:
          type: string
          pattern: ^[1-9][0-9]*[mhdw]$
          description: |
            A whole number of minutes, hours, days or weeks (`30m`, `6h`,
            `1d`, `2w`), from `1m` to `31d`. Responses use the largest exact
            unit, so `60m` reads back as `1h`. Runs get up to 10% jitter.
    MonitorCronSchedule:
      type: object
      required:
        - type
        - cron
        - timezone
      properties:
        type:
          type: string
          enum:
            - cron
        cron:
          type: string
          maxLength: 128
          description: >-
            Five-field cron expression, for example `0 9 * * 1-5`, without a
            `TZ=` prefix. Runs may be as often as every minute and at most 31
            days apart, checked in `timezone`: monthly passes; quarterly,
            yearly, the 31st and leap-day schedules are rejected. Runs get up to
            10 minutes of jitter.
        timezone:
          type: string
          description: >-
            IANA timezone, for example `Europe/Belgrade`. Optional in requests
            (default `UTC`); always returned.
    MonitorRunStatus:
      type: string
      enum:
        - queued
        - running
        - succeeded
        - failed
        - skipped
      description: >-
        `queued` is a manual run that has not started. `skipped` is a run that
        did not start, including a queued run cancelled by pausing the monitor.
        New statuses may be added; treat an unknown one as not finished.
    MonitorSearchTargetRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - query
      properties:
        type:
          type: string
          enum:
            - search
        query:
          type: string
          minLength: 1
          maxLength: 1000
          description: Search query to run on each run
        max_results:
          type: integer
          format: int32
          minimum: 1
          maximum: 20
          default: 20
          description: Maximum search results considered per query; the run can keep fewer.
        filters:
          $ref: '#/components/schemas/MonitorSearchFiltersRequest'
    MonitorPageTargetRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum:
            - page
        url:
          type: string
          format: uri
          minLength: 1
          maxLength: 2048
          description: Absolute `http(s)` URL of a public host, without credentials
    MonitorSearchFilters:
      type: object
      required:
        - freshness
        - include_domains
        - exclude_domains
      properties:
        freshness:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/MonitorFreshness'
          description: |
            Which result date puts a result in the run window: `published`,
            `updated`, or both (either date counts). Responses always list
            the values in use. `updated` uses the source's last-updated date
            with calendar-day precision, not a content-version or page-diff
            guarantee. URLs this monitor has already reported stay
            suppressed.
        include_domains:
          type: array
          maxItems: 20
          uniqueItems: true
          items:
            $ref: '#/components/schemas/MonitorDomain'
          description: >-
            Only results from these domains or their subdomains; `[]` for no
            restriction
        exclude_domains:
          type: array
          maxItems: 20
          uniqueItems: true
          items:
            $ref: '#/components/schemas/MonitorDomain'
          description: >-
            Results from these domains or their subdomains are dropped; may be
            `[]`
    MonitorSearchFiltersRequest:
      type: object
      additionalProperties: false
      properties:
        freshness:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/MonitorFreshness'
          description: Omit or send an empty array for both `published` and `updated`.
        include_domains:
          type: array
          maxItems: 20
          items:
            type: string
          description: >-
            Up to 20 bare host names such as `example.com`, without a scheme,
            path, or port. Only results from these domains or their subdomains
            are included.
        exclude_domains:
          type: array
          maxItems: 20
          items:
            type: string
          description: |
            Up to 20 host names whose results, and their subdomains', are
            dropped. A domain may not also be in `include_domains`.
    MonitorFreshness:
      type: string
      enum:
        - published
        - updated
      description: New values may be added; ignore unknown ones in responses.
    MonitorDomain:
      type: string
      maxLength: 253
      pattern: ^[a-z0-9-]+(\.[a-z0-9-]+)+$
      description: A bare host name, such as `example.com`.
  responses:
    MonitorBadRequest:
      description: Invalid request or reused idempotency key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
    MonitorUnauthorized:
      description: Invalid API key, expired token, or no credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
    MonitorPaymentRequired:
      description: API credits exhausted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
    MonitorForbidden:
      description: Monitors are not available to this API Group
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
    MonitorTooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/MonitorRetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
    MonitorBadGateway:
      description: The Monitor request failed; retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
    MonitorUnavailable:
      description: Monitor service unavailable; retry
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
    MonitorGatewayTimeout:
      description: The monitor service did not answer in time; retry
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorApiError'
  headers:
    MonitorRetryAfter:
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````