> ## 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 Monitors API Reference

> Lists your monitors, newest first.



## OpenAPI

````yaml /api-reference/openapi.json get /monitors
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:
    get:
      summary: List monitors
      description: Lists your monitors, newest first.
      operationId: get-monitors
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - active
              - paused
          description: Only return monitors with this status.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Maximum number of monitors to return.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            The `next_cursor` from the previous response. Omit for the first
            page.
        - name: name
          in: query
          required: false
          schema:
            type: string
          description: Filters monitors by name. Fuzzy, case-insensitive match.
        - name: page_no
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
          description: >-
            Page number, for page-based pagination. Mutually exclusive with
            `cursor`.
      responses:
        '200':
          description: Successful monitor list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorListResponse'
              example:
                code: 0
                msg: success
                request_id: req_abc123def456
                data:
                  monitors:
                    - monitor_id: mon_456
                      name: solid-state battery breakthroughs
                      type: topic
                      status: active
                      created_at: '2026-11-16T08:22:16Z'
                      schedule:
                        interval: 6h
                      condition: a substantive new development
                      query: solid-state battery breakthroughs
                      last_run:
                        run_id: run_790
                        status: completed
                        at: '2026-11-16T08:22:21Z'
                    - monitor_id: mon_123
                      name: shop.example.com/products/widget-pro
                      type: page
                      status: active
                      created_at: '2026-11-16T08:22:10Z'
                      schedule:
                        interval: 1h
                      condition: price drops more than 10%
                      urls:
                        - https://shop.example.com/products/widget-pro
                      last_run:
                        run_id: run_789
                        status: completed
                        at: '2026-11-16T14:00:07Z'
                  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'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    MonitorListResponse:
      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/MonitorListData'
    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
    MonitorListData:
      type: object
      properties:
        monitors:
          type: array
          items:
            $ref: '#/components/schemas/MonitorListItem'
          description: Monitors, newest first.
        next_cursor:
          type: string
          description: >-
            Pass as `cursor` to get the next page. Empty when there are no more
            results or when using `page_no`.
        total:
          type: integer
          description: >-
            Total number of matching monitors. Returned only when `page_no` is
            set.
    MonitorListItem:
      type: object
      properties:
        monitor_id:
          type: string
          description: The monitor id.
        name:
          type: string
          description: The monitor name.
        type:
          type: string
          description: '`topic` or `page`.'
        status:
          type: string
          description: '`active` or `paused`.'
        created_at:
          type: string
          format: date-time
          description: Creation time in ISO 8601.
        schedule:
          $ref: '#/components/schemas/MonitorScheduleConfig'
        condition:
          type:
            - string
            - 'null'
          description: The notification condition. `null` when not set.
        query:
          type: string
          description: The search query. Returned for `topic` monitors only.
        urls:
          type: array
          items:
            type: string
          description: The watched pages. Returned for `page` monitors only.
        last_run:
          $ref: '#/components/schemas/MonitorLastRun'
    MonitorScheduleConfig:
      type: object
      description: How often the monitor runs.
      properties:
        interval:
          type: string
          description: >-
            The run interval, such as `1h` or `1d`. Returned only when using
            `interval`.
        cron:
          type: string
          description: The cron expression. Returned only when using `cron`.
        timezone:
          type: string
          description: The time zone for `cron`. Returned only when using `cron`.
    MonitorLastRun:
      type: object
      description: The latest run. Returned only after the monitor has run.
      properties:
        run_id:
          type: string
          description: The run id.
        status:
          type: string
          description: >-
            The run status: `queued`, `processing`, `completed`, `skipped`, or
            `failed`.
        at:
          type: string
          format: date-time
          description: When the run finished, in ISO 8601.
  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.