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

# Update Monitor API Reference

> Updates a monitor, or pauses or resumes it. Send only the fields to change; `type` can't be changed. An update doesn't trigger a run.

**Effect of each change**

| You change | Effect |
| --- | --- |
| `topic.query` | Clears the results found so far; the next run starts over. |
| Other `topic` fields | Keeps the results found so far; the next run returns only unseen results. |
| `page.urls` | New URLs record a baseline; removed URLs are no longer compared. |
| `page.output_schema`, or `condition` on a `page` monitor with `output_schema` | The next run records a new baseline. |
| `condition` in other cases | Applies from the next run. |
| Any other field | The baseline is kept. |



## OpenAPI

````yaml /api-reference/openapi.json patch /monitors/{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}:
    patch:
      summary: Update a monitor
      description: >-
        Updates a monitor, or pauses or resumes it. Send only the fields to
        change; `type` can't be changed. An update doesn't trigger a run.


        **Effect of each change**


        | You change | Effect |

        | --- | --- |

        | `topic.query` | Clears the results found so far; the next run starts
        over. |

        | Other `topic` fields | Keeps the results found so far; the next run
        returns only unseen results. |

        | `page.urls` | New URLs record a baseline; removed URLs are no longer
        compared. |

        | `page.output_schema`, or `condition` on a `page` monitor with
        `output_schema` | The next run records a new baseline. |

        | `condition` in other cases | Applies from the next run. |

        | Any other field | The baseline is kept. |
      operationId: patch-monitor
      parameters:
        - $ref: '#/components/parameters/MonitorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorUpdateRequest'
            examples:
              pause:
                summary: Pause
                value:
                  status: paused
              schedule:
                summary: Change the schedule
                value:
                  schedule:
                    interval: 6h
      responses:
        '200':
          description: Successful monitor update response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorUpdateResponse'
              example:
                code: 0
                msg: success
                request_id: req_abc123def456
                data:
                  monitor_id: mon_123
                  name: shop.example.com/products/widget-pro
                  type: page
                  page:
                    urls:
                      - https://shop.example.com/products/widget-pro
                    output_schema:
                      - field_name: price
                        field_type: number
                        field_desc: Current price in USD
                  condition: price drops more than 10%
                  schedule:
                    interval: 1h
                  webhook:
                    url: https://example.com/hooks/octen
                  status: paused
                  pause_reason: user
                  last_run:
                    run_id: run_789
                    status: completed
                    at: '2026-11-16T14:00:07Z'
                  last_notified_at: '2026-11-16T14:00:07Z'
                  created_at: '2026-11-16T08:22:10Z'
                  notifications_7d: 1
        '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: Missing or invalid parameter
                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:
    MonitorUpdateRequest:
      type: object
      description: Request body for the Update Monitor API.
      properties:
        status:
          type: string
          enum:
            - active
            - paused
          description: >-
            `paused` stops scheduled runs; `active` resumes them. A monitor
            paused automatically for low balance stays paused after you top up
            until you send `active`.
        name:
          type: string
          maxLength: 256
          description: The monitor name.
        condition:
          type:
            - string
            - 'null'
          maxLength: 1000
          description: The notification condition. Send `null` or `""` to remove it.
        topic:
          type: object
          description: >-
            Search settings. `topic` monitors only. Send only the sub-fields to
            change; send `null` for a sub-field to reset it to its default.
          properties:
            query:
              type: string
              maxLength: 500
              description: The search query.
            include_domains:
              type: array
              items:
                type: string
                maxLength: 60
              maxItems: 1200
              description: A list of domains to specifically include in the search results.
            exclude_domains:
              type: array
              items:
                type: string
                maxLength: 60
              maxItems: 1200
              description: >-
                A list of domains to specifically exclude from the search
                results.
            highlight:
              type: object
              description: Controls highlight extraction from result pages.
              properties:
                enable:
                  type: boolean
                  description: If true, returns query-relevant highlight in each result.
                max_tokens:
                  type: integer
                  minimum: 100
                  maximum: 20000
                  description: Max tokens returned per highlight.
            full_content:
              type: object
              description: >-
                Controls whether to return the full raw content of each result
                page.
              properties:
                enable:
                  type: boolean
                  description: If true, returns `full_content` for each result.
                max_tokens:
                  type: integer
                  minimum: 100
                  maximum: 100000
                  description: Maximum tokens of full content included per result.
            include_images:
              type: boolean
              description: Whether to include images in each result.
            output_schema:
              type: array
              maxItems: 20
              items:
                $ref: '#/components/schemas/MonitorOutputSchemaField'
              description: >-
                Fields to extract from each result. Values are returned in
                `fields`. Replaces the existing list.
        page:
          type: object
          description: >-
            Page settings. `page` monitors only. Send only the sub-fields to
            change.
          properties:
            urls:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: string
                maxLength: 2048
              description: >-
                Public `http` or `https` URLs, each up to 2,048 bytes. Replaces
                the existing list.
            output_schema:
              type: array
              maxItems: 20
              items:
                $ref: '#/components/schemas/MonitorOutputSchemaField'
              description: Fields to watch on each page. Replaces the existing list.
        schedule:
          type: object
          description: How often the monitor runs. Use either `interval` or `cron`.
          properties:
            interval:
              type: string
              description: '`1h`–`100h` in hours, or `1d`–`30d` in days.'
            cron:
              type: string
              description: A cron expression. Runs must be at least 1 hour apart.
            timezone:
              type: string
              description: IANA time zone for `cron`. Defaults to `UTC`.
        webhook:
          type:
            - object
            - 'null'
          required:
            - url
          description: >-
            Where to push events. Send `null` to remove the webhook. Adding a
            webhook returns a new `secret`.
          properties:
            url:
              type: string
              maxLength: 2048
              description: A public HTTPS URL.
            headers:
              type:
                - object
                - 'null'
              maxProperties: 10
              additionalProperties:
                type: string
              description: >-
                Custom headers sent with each push, up to 10. Reserved headers
                such as `Content-Type` aren't allowed. Send `null` to clear
                them. Not returned in responses.
            rotate_secret:
              type: boolean
              description: >-
                If true, rotates the signing secret. The new `secret` is
                returned only in this response.
        email:
          type:
            - object
            - 'null'
          required:
            - to
          description: Email notifications. Send `null` to remove them.
          properties:
            to:
              type: array
              minItems: 1
              maxItems: 5
              items:
                type: string
              description: Recipient addresses.
        metadata:
          type:
            - object
            - 'null'
          maxProperties: 8
          additionalProperties:
            type: string
            maxLength: 512
          description: >-
            Your own key-value pairs. Replaces the existing object instead of
            merging; send `null` or `{}` to clear it. Up to 8 pairs; keys up to
            16 characters, string values up to 512 characters.
    MonitorUpdateResponse:
      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/MonitorUpdateData'
    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
    MonitorOutputSchemaField:
      type: object
      required:
        - field_name
        - field_type
      properties:
        field_name:
          type: string
          maxLength: 64
          description: >-
            The key of the field in `fields`. Letters, digits, and underscores
            only; can't start with a digit.
        field_type:
          type: string
          enum:
            - string
            - number
            - boolean
          description: The value type. Returns `null` when the value can't be extracted.
        field_desc:
          type: string
          maxLength: 500
          description: What the field holds, such as `Current price in USD`.
    MonitorUpdateData:
      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`.'
        topic:
          $ref: '#/components/schemas/MonitorTopicConfig'
        page:
          $ref: '#/components/schemas/MonitorPageConfig'
        condition:
          type:
            - string
            - 'null'
          description: The notification condition. `null` when not set.
        schedule:
          $ref: '#/components/schemas/MonitorScheduleConfig'
        webhook:
          type: object
          description: The webhook settings. Returned only when set.
          properties:
            url:
              type: string
              description: The webhook URL.
            secret:
              type: string
              description: >-
                The new webhook signing secret. Returned only when this update
                adds a webhook or sets `rotate_secret`.
        email:
          $ref: '#/components/schemas/MonitorEmailConfig'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Your key-value pairs. Returned only when set.
        status:
          type: string
          description: '`active` or `paused`.'
        pause_reason:
          type: string
          description: >-
            Why the monitor is paused: `user` (manually), `fetch_failed` or
            `judge_failed` (automatically, after repeated failures), or
            `insufficient_balance` (automatically, for low balance). Returned
            only when paused.
        next_run_at:
          type: string
          format: date-time
          description: The next scheduled run. Returned only when active.
        last_run:
          $ref: '#/components/schemas/MonitorLastRun'
        last_notified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the monitor last sent a notification. `null` if it hasn't
            notified yet.
        created_at:
          type: string
          format: date-time
          description: Creation time in ISO 8601.
        notifications_7d:
          type: integer
          description: Events generated in the past 7 days.
    MonitorTopicConfig:
      type: object
      description: Search settings for a topic monitor. Returned for `topic` monitors only.
      properties:
        query:
          type: string
          description: The search query.
        include_domains:
          type: array
          items:
            type: string
          description: Domains to include. `[]` when not set.
        exclude_domains:
          type: array
          items:
            type: string
          description: Domains to exclude. `[]` when not set.
        highlight:
          type: object
          description: Highlight settings.
          properties:
            enable:
              type: boolean
              description: Whether highlights are returned.
            max_tokens:
              type: integer
              description: Max tokens returned per highlight.
        full_content:
          type: object
          description: Full content settings.
          properties:
            enable:
              type: boolean
              description: Whether full content is returned.
            max_tokens:
              type: integer
              description: Maximum tokens of full content included per result.
        include_images:
          type: boolean
          description: Whether images are included.
        output_schema:
          type: array
          items:
            $ref: '#/components/schemas/MonitorOutputSchemaFieldInfo'
          description: Fields to extract. Returned only when set.
    MonitorPageConfig:
      type: object
      description: Settings for a page monitor. Returned for `page` monitors only.
      properties:
        urls:
          type: array
          items:
            type: string
          description: The watched page URLs.
        output_schema:
          type: array
          items:
            $ref: '#/components/schemas/MonitorOutputSchemaFieldInfo'
          description: Fields to watch on each page. Returned only when set.
    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`.
    MonitorEmailConfig:
      type: object
      description: Email notifications. Returned only when set.
      properties:
        to:
          type: array
          items:
            type: string
          description: Recipient addresses.
    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.
    MonitorOutputSchemaFieldInfo:
      type: object
      properties:
        field_name:
          type: string
          description: The key of the field in `fields`.
        field_type:
          type: string
          description: '`string`, `number`, or `boolean`.'
        field_desc:
          type: string
          description: What the field holds. Returned only when set.
  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.