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

# Get Monitor Run API Reference

> Returns a monitor run by id, including every result it checked.



## OpenAPI

````yaml /api-reference/openapi.json get /monitors/{id}/runs/{run_id}
openapi: 3.1.0
info:
  title: Octen API
  description: >-
    Octen API provides Broad Search, Web Search, Image Search, Video Search,
    Extract, Embeddings, VL Embeddings, Answer, and Deep Research services. The
    Web Search API searches ranked web results with optional filters,
    highlights, and full content. The Image Search API searches for images from
    a text query or an image. The Video Search API searches for videos from a
    text query. The Broad Search API decomposes a query into multiple
    sub-queries, searches them in parallel, and returns results grouped by
    sub-query. The Extract API extracts clean content from URLs, with optional
    query-focused highlights, page classification, and multimedia resources. The
    Embeddings API converts text into vector representations. The VL Embeddings
    API converts multimodal inputs into vector representations. The Answer API
    decomposes queries into multiple sub-queries for comprehensive search and
    synthesis. The Deep Research API runs a multi-round adaptive research
    pipeline that produces a structured research plan, executes iterative
    searches, and streams a final long-form report. The Pulse Search API
    generates the most likely URLs for a query in about 10ms, with optional
    highlights and full content in standard mode. The Monitor API watches a
    topic or a set of pages on a schedule, records changes that meet your
    condition as events, and pushes them by webhook or email, or lets you pull
    them through the API.
  version: 1.0.0
servers:
  - url: https://api.octen.ai
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /monitors/{id}/runs/{run_id}:
    get:
      summary: Get a monitor run
      description: Returns a monitor run by id, including every result it checked.
      operationId: get-monitor-run
      parameters:
        - $ref: '#/components/parameters/MonitorId'
        - name: run_id
          in: path
          required: true
          schema:
            type: string
          example: run_789
          description: >-
            The run id returned by Create Monitor (`first_run_id`), Trigger
            Monitor Run, or List Monitor Runs.
      responses:
        '200':
          description: Successful run response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorRunResponse'
              examples:
                page:
                  summary: Page monitor
                  value:
                    code: 0
                    msg: success
                    request_id: req_abc123def456
                    data:
                      run_id: run_789
                      monitor_id: mon_123
                      kind: scheduled
                      status: completed
                      scheduled_at: '2026-11-16T14:00:00Z'
                      started_at: '2026-11-16T14:00:01Z'
                      finished_at: '2026-11-16T14:00:07Z'
                      items_total: 1
                      items_changed: 1
                      items_notified: 1
                      usage:
                        num_queries: 0
                        num_urls: 1
                        cost: 0.003
                      items:
                        - url: https://shop.example.com/products/widget-pro
                          title: Widget Pro – Example Shop
                          change_status: changed
                          notified: true
                          delivered: true
                          event_id: evt_1
                          rule:
                            satisfied: true
                          fields:
                            price: 849
                          changed:
                            price:
                              previous: 999
                              current: 849
                              changed: true
                              delta: -150
                              pct: -0.1502
                          previous_detected_at: '2026-11-16T13:00:05Z'
                          full_content: |-
                            Widget Pro
                            Price: $849.00
                            In stock
                          judgment:
                            meaningful: true
                            confidence: high
                            reason: 'price: 999 → 849 (-15.0%) (price change < -10%)'
                topic:
                  summary: Topic monitor
                  value:
                    code: 0
                    msg: success
                    request_id: req_abc123def456
                    data:
                      run_id: run_792
                      monitor_id: mon_456
                      kind: scheduled
                      status: completed
                      scheduled_at: '2026-11-16T20:00:00Z'
                      started_at: '2026-11-16T20:00:01Z'
                      finished_at: '2026-11-16T20:00:04Z'
                      items_total: 2
                      items_changed: 1
                      items_notified: 1
                      usage:
                        num_queries: 1
                        num_urls: 0
                        cost: 0.002
                      items:
                        - url: >-
                            https://news.example.com/2026/11/16/solid-state-pilot-line
                          title: >-
                            Battery maker starts pilot production of solid-state
                            cells
                          change_status: new
                          notified: true
                          delivered: true
                          event_id: evt_3
                          fields:
                            headline: >-
                              Battery maker starts pilot production of
                              solid-state cells
                          highlight: >-
                            The company said its pilot line can produce enough
                            solid-state cells for road testing next year ...
                          authors: Example News
                          time_published: '2026-11-16T03:00:00Z'
                          judgment:
                            meaningful: true
                            confidence: high
                            reason: Matches the condition
                        - url: >-
                            https://research.example.org/papers/sulfide-electrolyte-cycle-life
                          title: >-
                            Sulfide electrolyte improves solid-state battery
                            cycle life
                          change_status: unchanged
                          notified: false
                          delivered: false
                          fields:
                            headline: >-
                              Sulfide electrolyte improves solid-state battery
                              cycle life
                          highlight: >-
                            Researchers report a sulfide electrolyte that keeps
                            more than 90% capacity after 1,000 cycles ...
                          authors: Example Research
                          time_published: '2026-11-12T09:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: >-
            Monitor or run not found — Returned when the monitor id or run id
            does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 404
                msg: Run not found
                request_id: req_abc123def456
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    MonitorId:
      name: id
      in: path
      required: true
      schema:
        type: string
      example: mon_123
      description: The monitor id returned by Create Monitor.
  schemas:
    MonitorRunResponse:
      type: object
      required:
        - request_id
      properties:
        code:
          type: integer
          description: Business status code. 0 indicates success.
        msg:
          type: string
          description: A message describing the result.
        request_id:
          type: string
          description: The unique identifier for this request.
        data:
          $ref: '#/components/schemas/MonitorRun'
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: Business status code. Non-zero values indicate an error.
        msg:
          type: string
          description: A message describing the error.
        request_id:
          type: string
          description: Unique identifier for the request.
      required:
        - code
        - msg
        - request_id
    MonitorRun:
      type: object
      properties:
        run_id:
          type: string
          description: The run id.
        monitor_id:
          type: string
          description: The monitor id.
        kind:
          type: string
          description: '`create` (the first run), `scheduled`, or `manual`.'
        status:
          type: string
          description: '`queued`, `processing`, `completed`, `skipped`, or `failed`.'
        scheduled_at:
          type: string
          format: date-time
          description: When the run was scheduled.
        started_at:
          type: string
          format: date-time
          description: When the run started.
        finished_at:
          type: string
          format: date-time
          description: When the run finished.
        skip_reason:
          type: string
          description: >-
            Why the run was skipped: `overlap` (the previous run is still
            going), `paused` (the monitor is paused), `insufficient_balance`
            (low balance), or `stale` (waited in the queue for over 1 hour while
            the system was busy). After 3 `insufficient_balance` skips in a row,
            the monitor is paused. Returned only for skipped runs.
        error_code:
          type: string
          description: >-
            The error code, such as `fetch_failed`, `judge_failed`, or
            `timeout`. Returned only for failed runs.
        items_total:
          type: integer
          description: >-
            Number of results or pages checked, excluding URLs that failed to
            fetch.
        items_changed:
          type: integer
          description: Number of new results or changed pages.
        items_notified:
          type: integer
          description: Number of events generated, that is, changes that met the condition.
        usage:
          $ref: '#/components/schemas/MonitorUsage'
        items:
          type: array
          items:
            $ref: '#/components/schemas/MonitorRunItem'
          description: Every result or page this run checked.
    MonitorUsage:
      type: object
      description: Usage for this run.
      properties:
        num_queries:
          type: integer
          description: Number of searches run. `topic` monitors only.
        num_urls:
          type: integer
          description: Number of pages fetched successfully. `page` monitors only.
        cost:
          type: number
          description: The run's cost in USD.
    MonitorRunItem:
      type: object
      properties:
        url:
          type: string
          description: The URL of the result or page.
        title:
          type: string
          description: The title of the page. Returned only when available.
        change_status:
          type: string
          description: >-
            `new`, `changed`, `baseline` (the first run), `unchanged` (already
            seen, or no change), or `failed` (fetch failed).
        notified:
          type: boolean
          description: Whether a notification was generated.
        delivered:
          type: boolean
          description: >-
            Whether it was delivered by webhook or email. `false` when no
            delivery channel is set.
        event_id:
          type: string
          description: The event id. Returned only for notified items.
        filtered:
          type: string
          description: >-
            Why the item wasn't notified, such as `duplicate` (a repeat of a
            result already pushed) or `stale` (old news published more than 5
            days ago; not applied on the first run). Returned only for filtered
            items on `topic` monitors.
        error:
          type: string
          description: >-
            Why the fetch failed, such as `fetch_failed`, `timeout`, `blocked`,
            or `not_found`. Returned only when `change_status` is `failed`.
        rule:
          type: object
          description: The result of a measurable condition. `page` monitors only.
          properties:
            satisfied:
              type: boolean
              description: Whether the condition is met.
        fields:
          type: object
          description: >-
            Values extracted with `output_schema`, keyed by `field_name`.
            Returned only when `output_schema` is set.
        changed:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MonitorFieldChange'
          description: >-
            Previous and current values of each `output_schema` field, and
            whether it changed, keyed by `field_name`. `page` monitors only.
        previous_detected_at:
          type: string
          format: date-time
          description: >-
            When the previous value was recorded, in ISO 8601. `page` monitors
            only.
        full_content:
          type: string
          description: >-
            Full raw page content. Always returned for `page` monitors; returned
            for `topic` monitors only if `full_content.enable` is true.
        images:
          type: array
          items:
            $ref: '#/components/schemas/MonitorImage'
          description: >-
            Images on the result page. Returned only when `topic.include_images`
            is true.
        highlight:
          type: string
          description: Query-relevant highlight snippets. `topic` monitors only.
        authors:
          type: string
          description: Website name or author. `topic` monitors only.
        time_published:
          type: string
          format: date-time
          description: Publish time in ISO 8601. `topic` monitors only.
        judgment:
          allOf:
            - $ref: '#/components/schemas/MonitorJudgment'
          description: >-
            The judgment result. Not returned for `unchanged`, `failed`, or
            filtered items.
    MonitorFieldChange:
      type: object
      properties:
        previous:
          type:
            - string
            - number
            - boolean
          description: >-
            The value before the change: the value at the last notification, or
            the first run's value if there hasn't been one.
        current:
          type:
            - string
            - number
            - boolean
          description: The value after the change.
        changed:
          type: boolean
          description: Whether the field changed.
        delta:
          type: number
          description: The amount of change. Number fields only.
        pct:
          type: number
          description: >-
            The relative change, such as `-0.5` for a 50% drop. Number fields
            only.
    MonitorImage:
      type: object
      properties:
        url:
          type: string
          description: The image URL.
        description:
          type: string
          description: Text description of the image. Returned only when available.
    MonitorJudgment:
      type: object
      description: The judgment result.
      properties:
        meaningful:
          type: boolean
          description: Whether the change was judged worth notifying.
        confidence:
          type: string
          enum:
            - high
            - medium
            - low
          description: Confidence of the judgment.
        reason:
          type: string
          description: >-
            Why the event was sent, such as `price: 51.77 → 45 (-13.1%) (price <
            50)`. The format may change; to read field values, use `changed` or
            `fields`. Not returned on the first run of a monitor with no
            condition.
  responses:
    Unauthorized:
      description: Invalid API Key — Returned when the API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            msg: Invalid API Key
            request_id: req_abc123def456
    RateLimited:
      description: >-
        Exceeding the rate limit — Returned when the request exceeds the
        configured rate limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 429
            msg: Exceeding the rate limit
            request_id: req_abc123def456
    InternalError:
      description: Internal error — Returned when an unexpected server-side error occurs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 500
            msg: Internal error
            request_id: req_abc123def456
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token used for request authentication. Alternatively, you can
        send the API key in the `x-api-key` header. Note: A payment method is
        required to use the API.
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key used for request authentication. Alternatively, you can send the
        key as a Bearer token in the `Authorization` header. Note: A payment
        method is required to use the API.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.