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

# Create Monitor API Reference

> Creates a monitor that watches a topic or up to 10 pages on a schedule. The first run starts right away and records a baseline. Each account can have up to 30 monitors, not counting deleted ones.



## OpenAPI

````yaml /api-reference/openapi.json post /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:
    post:
      summary: Create a monitor
      description: >-
        Creates a monitor that watches a topic or up to 10 pages on a schedule.
        The first run starts right away and records a baseline. Each account can
        have up to 30 monitors, not counting deleted ones.
      operationId: post-monitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCreateRequest'
            examples:
              page:
                summary: Page monitor
                value:
                  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
              topic:
                summary: Topic monitor
                value:
                  type: topic
                  topic:
                    query: solid-state battery breakthroughs
                    include_domains:
                      - news.example.com
                      - research.example.org
                    output_schema:
                      - field_name: headline
                        field_type: string
                        field_desc: Article headline
                  condition: a substantive new development
                  schedule:
                    interval: 6h
                  webhook:
                    url: https://example.com/hooks/octen
              minimal:
                summary: Minimal page monitor
                value:
                  type: page
                  page:
                    urls:
                      - https://example.com/terms
      responses:
        '200':
          description: Successful monitor creation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorCreateResponse'
              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
                    secret: octen_whsec_...
                  status: active
                  next_run_at: '2026-11-16T09:22:10Z'
                  last_notified_at: null
                  created_at: '2026-11-16T08:22:10Z'
                  notifications_7d: 0
                  first_run_id: run_788
        '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 required field: type'
                request_id: req_abc123def456
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientBalance'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    MonitorCreateRequest:
      type: object
      required:
        - type
      description: Request body for the Create Monitor API.
      properties:
        type:
          type: string
          enum:
            - topic
            - page
          description: >-
            The monitor type. `topic` finds new content on a topic. `page`
            watches the given URLs for changes.
        topic:
          $ref: '#/components/schemas/MonitorTopicOptions'
        page:
          $ref: '#/components/schemas/MonitorPageOptions'
        name:
          type: string
          maxLength: 256
          description: >-
            The monitor name. Defaults to the query, or the domain and path of
            the first URL.
        condition:
          type:
            - string
            - 'null'
          maxLength: 1000
          description: >-
            When to notify, in natural language, such as `price drops more than
            10%`. An empty string or `null` means no condition.


            Without a condition, the first run notifies once with
            `change_status` set to `baseline`. After that, a `topic` monitor
            notifies for each new relevant result; a `page` monitor notifies
            when any `output_schema` field changes or, without `output_schema`,
            when a model judges the page change meaningful.
        schedule:
          $ref: '#/components/schemas/MonitorSchedule'
        webhook:
          type: object
          required:
            - url
          description: Where to push events.
          properties:
            url:
              type: string
              maxLength: 2048
              description: >-
                A public HTTPS URL that receives one signed POST after each run
                that generates events. See [Monitor
                Webhooks](/api-reference/monitor-webhooks).
            headers:
              type: object
              maxProperties: 10
              additionalProperties:
                type: string
              description: >-
                Custom headers sent with each push, up to 10. Reserved headers
                such as `Content-Type` aren't allowed. Not returned in
                responses.
        email:
          type: object
          required:
            - to
          description: Email notifications. Each run's events are sent as one email.
          properties:
            to:
              type: array
              minItems: 1
              maxItems: 5
              items:
                type: string
              description: Recipient addresses.
        metadata:
          type: object
          maxProperties: 8
          additionalProperties:
            type: string
            maxLength: 512
          description: >-
            Your own key-value pairs, returned as-is in responses and webhooks.
            Up to 8 pairs; keys up to 16 characters, string values up to 512
            characters.
    MonitorCreateResponse:
      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/MonitorCreateData'
    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
    MonitorTopicOptions:
      type: object
      required:
        - query
      description: Search settings for a topic monitor. Required when `type` is `topic`.
      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:
          $ref: '#/components/schemas/MonitorHighlightOptions'
        full_content:
          $ref: '#/components/schemas/FullContentOptions'
        include_images:
          type: boolean
          default: false
          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`.
    MonitorPageOptions:
      type: object
      required:
        - urls
      description: Settings for a page monitor. Required when `type` is `page`.
      properties:
        urls:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: string
            maxLength: 2048
          description: >-
            Public `http` or `https` URLs to watch, each up to 2,048 bytes.
            Duplicates are removed.
        output_schema:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/MonitorOutputSchemaField'
          description: >-
            Fields to watch on each page. Without it, the monitor watches the
            whole page for meaningful changes.
    MonitorSchedule:
      type: object
      description: How often the monitor runs.
      properties:
        interval:
          type: string
          default: 1h
          description: '`1h`–`100h` in hours, or `1d`–`30d` in days.'
        cron:
          type: string
          description: >-
            A cron expression, used instead of `interval`. Runs must be at least
            1 hour apart.
        timezone:
          type: string
          default: UTC
          description: IANA time zone for `cron`, such as `America/New_York`.
    MonitorCreateData:
      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:
          allOf:
            - $ref: '#/components/schemas/MonitorScheduleConfig'
          description: 'How often the monitor runs. Defaults to `{"interval": "1h"}`.'
        webhook:
          type: object
          description: The webhook settings. Returned only when set.
          properties:
            url:
              type: string
              description: The webhook URL.
            secret:
              type: string
              description: The webhook signing secret. Returned only in this response.
        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` on creation.'
        next_run_at:
          type: string
          format: date-time
          description: The next scheduled run.
        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.
        first_run_id:
          type: string
          description: The id of the run started on creation.
    MonitorHighlightOptions:
      type: object
      description: Controls highlight extraction from result pages.
      properties:
        enable:
          type: boolean
          default: true
          description: If true, returns query-relevant highlight in each result.
        max_tokens:
          type: integer
          default: 1024
          minimum: 100
          maximum: 20000
          description: Max tokens returned per highlight.
    FullContentOptions:
      type: object
      description: Controls whether to return the full raw content of each result page.
      properties:
        enable:
          type: boolean
          default: false
          description: If true, returns full_content for each result.
        max_tokens:
          type: integer
          default: 2048
          minimum: 100
          maximum: 100000
          description: Maximum tokens of full content included per result.
    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`.
    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.
    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
    InsufficientBalance:
      description: >-
        Insufficient balance in account — Returned when the account balance is
        insufficient to complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 403
            msg: Insufficient balance in account
            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.