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

> Lists the events a monitor generated. Events include only a content preview; get the full content from [Get Monitor Run](/api-reference/get-monitor-run).



## OpenAPI

````yaml /api-reference/openapi.json get /monitors/{id}/events
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}/events:
    get:
      summary: List monitor events
      description: >-
        Lists the events a monitor generated. Events include only a content
        preview; get the full content from [Get Monitor
        Run](/api-reference/get-monitor-run).
      operationId: get-monitor-events
      parameters:
        - $ref: '#/components/parameters/MonitorId'
        - name: run_id
          in: query
          required: false
          schema:
            type: string
          description: Only return events from this run.
        - 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: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 20
          description: Maximum number of events 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 event list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorEventListResponse'
              example:
                code: 0
                msg: success
                request_id: req_abc123def456
                data:
                  events:
                    - event_id: evt_1
                      event_type: monitor.change
                      monitor_id: mon_123
                      run_id: run_789
                      url: https://shop.example.com/products/widget-pro
                      title: Widget Pro – Example Shop
                      change_status: changed
                      fields:
                        price: 849
                      changed:
                        price:
                          previous: 999
                          current: 849
                          changed: true
                          delta: -150
                          pct: -0.1502
                      previous_detected_at: '2026-11-16T13:00:05Z'
                      content_preview: |-
                        Widget Pro
                        Price: $849.00
                        In stock
                      judgment:
                        meaningful: true
                        confidence: high
                        reason: 'price: 999 → 849 (-15.0%) (price change < -10%)'
                      delivered: true
                      detected_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 20'
                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:
    MonitorEventListResponse:
      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/MonitorEventListData'
    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
    MonitorEventListData:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/MonitorEvent'
          description: Events, newest first.
        next_cursor:
          type: string
          description: >-
            Pass as `cursor` to get the next page. Empty when there are no more
            results.
    MonitorEvent:
      type: object
      properties:
        event_id:
          type: string
          description: The event id.
        event_type:
          type: string
          description: >-
            `monitor.new` for a new `topic` result, or `monitor.change` for a
            `page` change.
        monitor_id:
          type: string
          description: The monitor id.
        run_id:
          type: string
          description: The run that generated the event.
        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`, or `baseline` (the first run).'
        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.
        content_preview:
          type: string
          description: >-
            The first 500 characters of the content. Always returned for `page`
            events; returned for `topic` events when `full_content.enable` is
            true.
        highlight:
          type: string
          description: Query-relevant highlight snippets. `topic` monitors only.
        images:
          type: array
          items:
            $ref: '#/components/schemas/MonitorImage'
          description: >-
            Images on the result page. Returned only when `topic.include_images`
            is true.
        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:
          $ref: '#/components/schemas/MonitorJudgment'
        delivered:
          type: boolean
          description: >-
            Whether it was delivered by webhook or email. `false` when no
            delivery channel is set.
        detected_at:
          type: string
          format: date-time
          description: When the change was detected, in ISO 8601.
    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
    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.