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

# Get a run

> Retrieve one Monitor run, including its state, counts, changes, and target errors.

A run is available as soon as [Run a monitor now](https://docs.perplexity.ai/api-reference/monitors-run-post.md) returns it. Read `status` to check its progress, `changes` for findings, and `target_errors` for Page targets that could not be read.

Every run includes `usage.searches`, `usage.fetched_urls`, and an estimated `usage.cost`, with `total_cost` and `currency` (`USD`). Usage and cost are zero unless the run succeeds. See [Monitor API pricing](https://docs.perplexity.ai/docs/getting-started/pricing.md#monitor-api-pricing) for rates.

A failed run's `error` has `code` and `message`; a skipped run has `skip_reason` and `message`. Use the typed code or reason rather than parsing message text.

Each Page target error has `type`, `url`, `code`, and `message`. An error with code `http_status` also includes `status_code`; other codes distinguish blocked pages, missing content, timeouts, and fetch failures. Allow for new codes.

## Read changes

* Search results: `changes[].type` is `search_result`. A result can include a title, snippet, `published_at`, and `last_updated_at`; unavailable fields are omitted rather than set to `null`.
* Page changes: `changes[].type` is `page_change`. The `diff` contains unified text, added and removed line counts, and a `truncated` flag. Line counts cover the full diff even when the unified text is truncated.
* Change IDs: `changes[].id` stays the same wherever the same finding is reported. Use it to deduplicate findings across runs and webhooks, and skip change types you do not recognize.

Timestamps use RFC 3339 in UTC with whole seconds. A Search result's `last_updated_at` is the source's last-updated date, at calendar-day precision, not the exact time its content changed. `published_at` is its publication date; selecting `updated` freshness does not make URLs already reported by this monitor eligible again. `finished_at` is omitted until the run ends, and `window` is omitted while it is queued.

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


## OpenAPI

````yaml get /v1/monitors/{monitor_id}/runs/{run_id}
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/{monitor_id}/runs/{run_id}:
    get:
      tags:
        - Monitors
      summary: Get a run
      description: >-
        Returns one run with its changes and target errors. A run is visible as
        soon as run-now returns it.
      operationId: getMonitorRun
      parameters:
        - $ref: '#/components/parameters/MonitorId'
        - $ref: '#/components/parameters/MonitorRunId'
      responses:
        '200':
          description: The run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorRun'
              example:
                id: run_01JC90AB2C3D4E5F6G7H8J9K0M
                object: monitor.run
                monitor_id: mon_01JC8ZK3Q4V5W6X7Y8Z9A0B1C2
                trigger: schedule
                status: succeeded
                window:
                  from: '2026-11-11T09:00:00Z'
                  to: '2026-11-12T09:00:00Z'
                counts:
                  candidates: 14
                  changes: 2
                  errors: 1
                usage:
                  searches: 1
                  fetched_urls: 0
                  cost:
                    total_cost: 0.001
                    currency: USD
                changes:
                  - id: chg_3f2a9b1c7d4e5f60718293a4b5c6d7e8
                    type: search_result
                    url: https://techcrunch.com/2026/11/11/acme-launches-x
                    title: Acme launches X, its first robot vacuum
                    confidence: 0.93
                    snippet: >-
                      Acme Corp on Tuesday announced X, a $499 robot vacuum
                      shipping in December...
                    published_at: '2026-11-11T00:00:00Z'
                  - id: chg_9c41d2e3f4a5b6c7d8e9f0a1b2c3d4e5
                    type: page_change
                    url: https://acme.com/pricing
                    title: Pricing | Acme
                    confidence: 0.96
                    diff:
                      unified: |
                        @@ -12,3 +12,3 @@
                         Plans
                        -Pro $20/mo
                        +Pro $25/mo
                         Enterprise
                      added_lines: 1
                      removed_lines: 1
                      truncated: false
                    previous_fetched_at: '2026-11-11T09:00:04Z'
                    fetched_at: '2026-11-12T09:00:03Z'
                target_errors:
                  - type: page
                    url: https://acme.com/changelog
                    code: http_status
                    status_code: 503
                    message: 'page fetch failed: the page answered with HTTP 503'
                created_at: '2026-11-12T09:00:00Z'
                finished_at: '2026-11-12T09:00:41Z'
        '401':
          $ref: '#/components/responses/MonitorUnauthorized'
        '403':
          $ref: '#/components/responses/MonitorForbidden'
        '404':
          description: Monitor or run not found
          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:
    MonitorId:
      name: monitor_id
      in: path
      required: true
      schema:
        type: string
      description: Monitor identifier (mon_...)
    MonitorRunId:
      name: run_id
      in: path
      required: true
      schema:
        type: string
      description: Run identifier (run_...)
  schemas:
    MonitorRun:
      type: object
      required:
        - id
        - object
        - monitor_id
        - trigger
        - status
        - counts
        - usage
        - changes
        - target_errors
        - created_at
      properties:
        id:
          type: string
          maxLength: 64
          description: Opaque ID with the prefix `run_`
        object:
          type: string
          enum:
            - monitor.run
        monitor_id:
          type: string
        trigger:
          $ref: '#/components/schemas/MonitorRunTrigger'
        status:
          $ref: '#/components/schemas/MonitorRunStatus'
        window:
          allOf:
            - $ref: '#/components/schemas/MonitorRunWindow'
          description: Omitted while the run is `queued`
        counts:
          $ref: '#/components/schemas/MonitorRunCounts'
        usage:
          $ref: '#/components/schemas/MonitorRunUsage'
        changes:
          type: array
          items:
            $ref: '#/components/schemas/MonitorChange'
        target_errors:
          type: array
          items:
            $ref: '#/components/schemas/MonitorTargetError'
        error:
          allOf:
            - $ref: '#/components/schemas/MonitorRunError'
          description: Only on `failed` and `skipped` runs
        created_at:
          $ref: '#/components/schemas/MonitorTimestamp'
        finished_at:
          allOf:
            - $ref: '#/components/schemas/MonitorTimestamp'
          description: Omitted until the run ends
    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
    MonitorRunTrigger:
      type: string
      enum:
        - schedule
        - manual
      description: What started the run. New triggers may be added; accept unknown values.
    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.
    MonitorRunWindow:
      type: object
      description: >
        The time range a run covers, `(from, to]`. 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.
      required:
        - from
        - to
      properties:
        from:
          $ref: '#/components/schemas/MonitorTimestamp'
        to:
          $ref: '#/components/schemas/MonitorTimestamp'
    MonitorRunCounts:
      type: object
      required:
        - candidates
        - changes
        - errors
      properties:
        candidates:
          type: integer
          format: int32
          description: New search results or changed pages before judging
        changes:
          type: integer
          format: int32
        errors:
          type: integer
          format: int32
          description: Target fetch failures and candidates that could not be judged.
    MonitorRunUsage:
      type: object
      description: >-
        Usage for the run. Only a `succeeded` run has nonzero usage. Search
        monitors report successful search calls in `searches` but are billed
        once per run; Page monitors report counted `fetched_urls`. The other
        counter is zero. Judging is included in the price.
      required:
        - searches
        - fetched_urls
        - cost
      properties:
        searches:
          type: integer
          format: int32
          description: >-
            Number of successful searches, including searches that returned no
            results. A succeeded Search run is billed once, regardless of this
            count.
        fetched_urls:
          type: integer
          format: int32
          description: Pages the run fetched
        cost:
          $ref: '#/components/schemas/MonitorRunCost'
    MonitorChange:
      description: >-
        One finding the judge kept. New types may be added; skip changes with an
        unknown type.
      oneOf:
        - $ref: '#/components/schemas/MonitorSearchResultChange'
        - $ref: '#/components/schemas/MonitorPageChange'
      discriminator:
        propertyName: type
        mapping:
          search_result: '#/components/schemas/MonitorSearchResultChange'
          page_change: '#/components/schemas/MonitorPageChange'
    MonitorTargetError:
      description: |
        A target that could not be read this run; its baseline is kept. New
        types may be added; skip errors with an unknown type.
      oneOf:
        - $ref: '#/components/schemas/MonitorPageTargetError'
      discriminator:
        propertyName: type
        mapping:
          page: '#/components/schemas/MonitorPageTargetError'
    MonitorRunError:
      type: object
      description: |
        Why a run failed or was skipped: a `failed` run has `code`, a
        `skipped` run has `skip_reason`, the pause reason that refused it.
      required:
        - message
      properties:
        code:
          $ref: '#/components/schemas/MonitorRunFailureCode'
        skip_reason:
          $ref: '#/components/schemas/MonitorPauseReason'
        message:
          type: string
          description: Human-readable; may change. Do not parse.
    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`.
    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.
    MonitorRunCost:
      type: object
      description: >-
        Estimated run cost at list prices: $0.001 per succeeded Search run or
        counted fetched URL in a succeeded Page run, rounded to 5 decimal
        places. This is not the amount charged.
      required:
        - total_cost
        - currency
      properties:
        total_cost:
          format: double
          type: number
        currency:
          $ref: '#/components/schemas/MonitorCurrency'
    MonitorSearchResultChange:
      type: object
      description: A search result new to the query since the last run
      required:
        - id
        - type
        - url
        - confidence
      properties:
        id:
          $ref: '#/components/schemas/MonitorChangeId'
        type:
          type: string
          enum:
            - search_result
        url:
          type: string
        title:
          type: string
          description: Omitted when unknown
        confidence:
          type: number
          format: double
          minimum: 0
          maximum: 1
          description: |
            Score from 0 to 1 that the change matches `goal`; higher is more
            confident. Compare scores within one monitor; the scale may be
            recalibrated.
        snippet:
          type: string
          maxLength: 500
          description: Text from the result, when the source has it
        published_at:
          allOf:
            - $ref: '#/components/schemas/MonitorTimestamp'
          description: When the source reports one
        last_updated_at:
          allOf:
            - $ref: '#/components/schemas/MonitorTimestamp'
          description: >-
            The source's last-updated date, at calendar-day precision, when it
            has one
    MonitorPageChange:
      type: object
      description: A meaningful change to a page target
      required:
        - id
        - type
        - url
        - confidence
        - diff
        - previous_fetched_at
        - fetched_at
      properties:
        id:
          $ref: '#/components/schemas/MonitorChangeId'
        type:
          type: string
          enum:
            - page_change
        url:
          type: string
        title:
          type: string
          description: Omitted when unknown
        confidence:
          type: number
          format: double
          minimum: 0
          maximum: 1
          description: |
            Score from 0 to 1 that the change matches `goal`; higher is more
            confident. Compare scores within one monitor; the scale may be
            recalibrated.
        diff:
          $ref: '#/components/schemas/MonitorDiff'
        previous_fetched_at:
          allOf:
            - $ref: '#/components/schemas/MonitorTimestamp'
          description: When the earlier of the two compared snapshots was fetched
        fetched_at:
          allOf:
            - $ref: '#/components/schemas/MonitorTimestamp'
          description: When the later snapshot was fetched
    MonitorPageTargetError:
      type: object
      description: A page target that could not be read this run
      required:
        - type
        - url
        - code
        - message
      properties:
        type:
          type: string
          enum:
            - page
        url:
          type: string
        code:
          $ref: '#/components/schemas/MonitorTargetErrorCode'
        status_code:
          type: integer
          format: int32
          description: The page's HTTP status; only with `http_status`
        message:
          type: string
          description: Human-readable; may change. Do not parse.
    MonitorRunFailureCode:
      type: string
      enum:
        - gate_unavailable
        - detect_failed
        - judge_failed
        - source_failed
        - notify_failed
        - timed_out
      description: >-
        Why a run failed: it could not start (`gate_unavailable`), retrieval
        failed (`detect_failed`), judging failed (`judge_failed`), every source
        failed (`source_failed`), the notification could not be scheduled
        (`notify_failed`), or the run timed out (`timed_out`). New codes may be
        added; treat an unknown one as a failure to retry on 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.
    MonitorCurrency:
      type: string
      description: Currency code for cost values
      enum:
        - USD
    MonitorChangeId:
      type: string
      maxLength: 64
      description: >-
        Stable opaque ID with the prefix `chg_`. Use it to deduplicate the same
        finding across runs and webhook deliveries.
    MonitorDiff:
      type: object
      description: Text changes between two page checks.
      required:
        - unified
        - added_lines
        - removed_lines
        - truncated
      properties:
        unified:
          type: string
          maxLength: 24576
          description: |
            Unified diff without file headers: `@@ -l,s +l,s @@` hunks with one
            context line, each line prefixed with ` `, `-` or `+` and ending in
            `\n`. Any diff library or viewer reads it. Limited to 24 KiB
            (24,576 UTF-8 bytes).
        added_lines:
          type: integer
          format: int32
          minimum: 0
          description: Added lines in the whole diff, also when `unified` was cut
        removed_lines:
          type: integer
          format: int32
          minimum: 0
          description: Removed lines in the whole diff, also when `unified` was cut
        truncated:
          type: boolean
          description: |
            Whether `unified` was cut to fit the 24 KiB byte limit. It keeps
            complete lines where possible; an oversized line can be shortened
            at a UTF-8 character boundary. Its last hunk header counts only
            the lines shown.
    MonitorTargetErrorCode:
      type: string
      enum:
        - invalid_url
        - blocked
        - no_content
        - load_failed
        - timeout
        - fetch_unavailable
        - http_status
      description: >-
        Why the page could not be read: the URL is not valid (`invalid_url`),
        the site blocked the request (`blocked`), the page has no readable text
        (`no_content`), loading failed (`load_failed`) or timed out (`timeout`),
        page retrieval is temporarily unavailable (`fetch_unavailable`), or the
        page returned an error status (`http_status`, with `status_code`). New
        codes may be added.
  responses:
    MonitorUnauthorized:
      description: Invalid API key, expired token, or no credits
      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

````