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

# List Monitor Runs API Reference

> Lists a monitor's runs, including runs that found no changes.



## OpenAPI

````yaml /api-reference/openapi.json get /monitors/{id}/runs
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:
    get:
      summary: List monitor runs
      description: Lists a monitor's runs, including runs that found no changes.
      operationId: get-monitor-runs
      parameters:
        - $ref: '#/components/parameters/MonitorId'
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - queued
              - processing
              - completed
              - skipped
              - failed
          description: Only return runs with this status.
        - name: order_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - time_desc
              - time_asc
            default: time_desc
          description: Newest first or oldest first.
        - name: only_changes
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: If true, returns only runs with changes.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Maximum number of runs to return.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            The `next_cursor` from the previous response. Omit for the first
            page.
      responses:
        '200':
          description: Successful run list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorRunListResponse'
              example:
                code: 0
                msg: success
                request_id: req_abc123def456
                data:
                  runs:
                    - run_id: run_790
                      kind: create
                      status: completed
                      scheduled_at: '2026-11-16T08:22:16Z'
                      started_at: '2026-11-16T08:22:17Z'
                      finished_at: '2026-11-16T08:22:21Z'
                      items_total: 10
                      items_changed: 10
                      items_notified: 3
                      usage:
                        num_queries: 1
                        num_urls: 0
                        cost: 0.002
                  next_cursor: ''
        '400':
          description: >-
            Invalid params — Returned when a required parameter is missing or
            invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                msg: 'Invalid params: limit must be an integer between 1 and 100'
                request_id: req_abc123def456
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/MonitorNotFound'
        '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:
    MonitorRunListResponse:
      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/MonitorRunListData'
    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
    MonitorRunListData:
      type: object
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/MonitorRunSummary'
          description: Runs on this page.
        next_cursor:
          type: string
          description: >-
            Pass as `cursor` to get the next page. Empty when there are no more
            results.
    MonitorRunSummary:
      type: object
      properties:
        run_id:
          type: string
          description: The run 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'
    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.
  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
    MonitorNotFound:
      description: >-
        Monitor not found — Returned when the monitor id does not exist or was
        deleted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            msg: Monitor not found
            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.