Orq.ai Monitors API

openapi: 3.2.0
info:
  title: orq.ai Monitors API
  version: '2.0'
  description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Monitors
  description: Monitors are custom observability dashboards for traces, runtime metrics, and logs. Each monitor holds widgets that chart one telemetry query. List the metrics, operations, and dimensions available to your workspace with `GET /v3/telemetry/capabilities`, or start from a preset with `GET /v2/monitors/presets`.
paths:
  /v2/monitors:
    get:
      tags:
      - Monitors
      summary: List monitors
      description: Returns the monitors visible to the caller, newest first. A human filtering by project sees that project's monitors plus workspace-wide monitors. A project-scoped API key sees only monitors in its strict project scope. Use `starting_after` or `ending_before` to page.
      operationId: MonitorList
      parameters:
      - name: limit
        in: query
        description: Page size, 1-200. Unset uses the server default (25).
        schema:
          type: integer
          format: int32
      - name: starting_after
        in: query
        description: "Cursor for forward pagination. Set to the `monitor_id` of the last\n item from the previous page."
        schema:
          type: string
      - name: ending_before
        in: query
        description: "Cursor for backward pagination. Set to the `monitor_id` of the\n first item from the previous page."
        schema:
          type: string
      - name: project_id
        in: query
        description: "Restrict results to one project. Human callers also see workspace-wide\n monitors; a project-scoped API key sees only its strict project scope."
        schema:
          type: string
      - name: search
        in: query
        description: Case-insensitive substring match on display name and description.
        schema:
          type: string
      - name: workspace_wide
        in: query
        description: "Restrict results by scope. Set true for workspace-wide monitors only,\n false for project-scoped monitors only; omit to return both."
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMonitorsResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: monitors
      x-speakeasy-name-override: list
      x-code-samples:
      - lang: TypeScript
        source: 'import { Orq } from ''@orq-ai/node'';

          const orq = new Orq({ apiKey: process.env.ORQ_API_KEY });

          await orq.monitors.list({ projectId: ''proj_01J81V5RZPVTDHXBV6M2YVJHRB'', limit: 25 });

          '
    post:
      tags:
      - Monitors
      summary: Create a monitor
      description: Creates a monitor (custom observability dashboard) in the workspace. Set `project_id` to scope the monitor to a project; omit it to create a workspace-wide monitor, which requires admin access.
      operationId: MonitorCreate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMonitorRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMonitorResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: monitors
      x-speakeasy-name-override: create
      x-code-samples:
      - lang: TypeScript
        source: 'import { Orq } from ''@orq-ai/node'';

          const orq = new Orq({ apiKey: process.env.ORQ_API_KEY });

          await orq.monitors.create({ displayName: ''LLM cost'', projectId: ''proj_01J81V5RZPVTDHXBV6M2YVJHRB'', defaultRange: ''7d'', widgets: [{ widgetId: ''cost'', type: ''timeseries'', title: ''Cost by model'', queries: [{ metric: ''genai.cost'', groupBy: [''model''] }], layout: { x: 0, y: 0, w: 12, h: 4 } }] });

          '
  /v2/monitors/presets:
    get:
      tags:
      - Monitors
      summary: List monitor presets
      description: Returns the built-in monitor templates (preset dashboards and preset widgets). Presets are defined by the platform and versioned with it; create a monitor from a preset by copying its widgets into a create request and stamping `preset_key`.
      operationId: MonitorListPresets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMonitorPresetsResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: monitors
      x-speakeasy-name-override: listPresets
      x-code-samples:
      - lang: TypeScript
        source: 'import { Orq } from ''@orq-ai/node'';

          const orq = new Orq({ apiKey: process.env.ORQ_API_KEY });

          await orq.monitors.listPresets();

          '
  /v2/monitors/{monitor_id}:
    get:
      tags:
      - Monitors
      summary: Retrieve a monitor
      description: Retrieves a monitor by ID.
      operationId: MonitorGet
      parameters:
      - name: monitor_id
        in: path
        description: Monitor ID to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMonitorResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: monitors
      x-speakeasy-name-override: get
      x-code-samples:
      - lang: TypeScript
        source: 'import { Orq } from ''@orq-ai/node'';

          const orq = new Orq({ apiKey: process.env.ORQ_API_KEY });

          await orq.monitors.get({ monitorId: ''monitor_01J81V5RZPVTDHXBV6M2YVJHRA'' });

          '
    delete:
      tags:
      - Monitors
      summary: Delete a monitor
      description: Permanently deletes a monitor. Widgets are stored inline, so no other resources are affected.
      operationId: MonitorDelete
      parameters:
      - name: monitor_id
        in: path
        description: Monitor ID to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMonitorResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: monitors
      x-speakeasy-name-override: delete
      x-code-samples:
      - lang: TypeScript
        source: 'import { Orq } from ''@orq-ai/node'';

          const orq = new Orq({ apiKey: process.env.ORQ_API_KEY });

          await orq.monitors.delete({ monitorId: ''monitor_01J81V5RZPVTDHXBV6M2YVJHRA'' });

          '
    patch:
      tags:
      - Monitors
      summary: Update a monitor
      description: 'Updates monitor metadata and widgets. With `update_mask`, listed paths are replaced and `widgets` may be explicitly cleared. Without `update_mask`, legacy behavior is preserved: a non-empty `widgets` array replaces the set and an empty or omitted array keeps it. `project_id` is immutable.'
      operationId: MonitorUpdate
      parameters:
      - name: monitor_id
        in: path
        description: Monitor ID to update.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMonitorRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMonitorResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: monitors
      x-speakeasy-name-override: update
      x-code-samples:
      - lang: TypeScript
        source: 'import { Orq } from ''@orq-ai/node'';

          const orq = new Orq({ apiKey: process.env.ORQ_API_KEY });

          await orq.monitors.update({ monitorId: ''monitor_01J81V5RZPVTDHXBV6M2YVJHRA'', displayName: ''LLM cost (weekly)'', defaultRange: ''30d'' });

          '
components:
  schemas:
    MonitorWidgetDisplay:
      type: object
      properties:
        visualization:
          enum:
          - lines
          - bars
          - area
          type: string
          description: Chart style for timeseries widgets.
        unit:
          enum:
          - count
          - cost
          - duration
          - percent
          - bytes
          type: string
          description: Unit used for axis and value formatting.
        sort:
          enum:
          - desc
          - asc
          type: string
          description: Value ordering for toplist widgets.
        show_overall:
          type: boolean
          description: "When true, toplist widgets also show the overall total across all\n groups for the window."
        target:
          type: number
          description: Optional threshold line rendered on timeseries widgets.
          format: double
        decimals:
          type: integer
          description: Decimal places used when formatting values.
          format: int32
        show_others:
          type: boolean
          description: "When true, toplist widgets show the combined value of groups outside\n the configured limit."
        show_percentages:
          type: boolean
          description: "When true, toplist widget values are shown as a percentage of the\n overall total."
    MonitorWidgetQuery:
      required:
      - metric
      type: object
      properties:
        source:
          description: Source queried through QueryTelemetry.
          $ref: '#/components/schemas/MonitorTelemetrySource'
        metric:
          type: string
          description: "Source-owned metric identifier. Static `genai.*` trace metrics are\n validated when saved; runtime metrics, logs, and raw trace aggregates\n are validated by the caller-scoped telemetry capability/query service."
        operation:
          type: string
          description: Source-owned aggregation operation advertised by telemetry capabilities.
        group_by:
          type: array
          items:
            type: string
          description: "Reporting dimensions to break down by. Valid dimensions depend on\n the metric; validated when the monitor is saved."
        filters:
          type: array
          items:
            $ref: '#/components/schemas/MonitorFilter'
          description: Reporting filters combined with AND.
        grain:
          enum:
          - auto
          - minute
          - hour
          - day
          type: string
          description: Requested bucket grain for timeseries widgets.
        limit:
          type: integer
          description: Row cap. Zero uses the reporting default. For toplist widgets this is the top-N group count.
          format: int32
    DeleteMonitorResponse:
      type: object
      properties: {}
    MonitorWidget:
      required:
      - widget_id
      - type
      - title
      - queries
      - layout
      type: object
      properties:
        widget_id:
          type: string
          description: "Widget identifier, unique within the monitor. Provide your own or\n leave empty to have the server assign one."
        type:
          enum:
          - timeseries
          - toplist
          - table
          - bignumber
          type: string
          description: Widget rendering type.
        title:
          type: string
          description: Title shown in the widget header.
        queries:
          type: array
          items:
            $ref: '#/components/schemas/MonitorWidgetQuery'
          description: "The one query feeding the widget. It maps onto QueryTelemetry; the\n viewer's time range, time zone, and the query mode derived from the\n widget type are supplied at render time."
        display:
          description: Display options such as visualization style and unit. `null` when none are saved.
          anyOf:
          - allOf:
            - $ref: '#/components/schemas/MonitorWidgetDisplay'
          - type: 'null'
        layout:
          allOf:
          - $ref: '#/components/schemas/MonitorWidgetLayout'
          description: Position and size on the monitor grid.
    MonitorFilter:
      required:
      - field
      - op
      - values
      type: object
      properties:
        field:
          type: string
          description: "Reporting dimension to filter on. Valid fields depend on the\n metric; validated when the monitor is saved."
        op:
          enum:
          - eq
          - neq
          - in
          - not_in
          - gt
          - gte
          - lt
          - lte
          - between
          - contains
          - exists
          - not_exists
          type: string
          description: Predicate operator. `eq` and `neq` accept exactly one value; `in` and `not_in` accept 1-100 values.
        values:
          type: array
          items:
            type: string
          description: Values compared against the selected field.
    ListMonitorPresetsResponse:
      required:
      - object
      - data
      type: object
      properties:
        object:
          type: string
          description: Object discriminator for list responses; always `list`.
        data:
          type: array
          items:
            $ref: '#/components/schemas/MonitorPreset'
          description: Built-in presets, dashboards first.
    GetMonitorResponse:
      required:
      - monitor
      type: object
      properties:
        monitor:
          allOf:
          - $ref: '#/components/schemas/Monitor'
          description: Requested monitor.
    CreateMonitorRequest:
      required:
      - display_name
      type: object
      properties:
        display_name:
          type: string
          description: Workspace-unique display name.
        description:
          type: string
          description: Short human-readable summary of what the monitor tracks.
        project_id:
          type: string
          description: "Project that should own the monitor. Omit to create a\n workspace-wide monitor (requires admin access)."
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/MonitorWidget'
          description: Widgets to render on the monitor. Empty creates a valid blank monitor.
        default_range:
          type: string
          description: Default relative time range applied when the monitor opens.
        preset_key:
          enum:
          - genai-overview
          - cost-analysis
          - latency
          - quality
          - widget-spans
          - widget-latency
          - widget-total-llm-cost
          - widget-token-count
          - widget-scores
          - widget-time-to-first-token
          - widget-tool-executions
          - widget-tool-error-rate
          - widget-tool-duration-p50
          type: string
          description: Known preset used to create the monitor. Empty when built from scratch.
    MonitorWidgetLayout:
      required:
      - x
      - y
      - w
      - h
      type: object
      properties:
        x:
          type: integer
          description: Column offset in grid units.
          format: int32
        y:
          type: integer
          description: Row offset in grid units.
          format: int32
        w:
          type: integer
          description: Width in grid units.
          format: int32
        h:
          type: integer
          description: Height in grid units.
          format: int32
    Monitor:
      required:
      - monitor_id
      - display_name
      - description
      - project_id
      - widgets
      - preset_key
      - created_at
      - updated_at
      - created_by_id
      - updated_by_id
      type: object
      properties:
        monitor_id:
          type: string
          description: "Unique monitor identifier assigned by ORQ, for example\n `monitor_01H...`. Use this value in retrieve, update, and delete\n requests."
        display_name:
          type: string
          description: Workspace-unique display name.
        description:
          type: string
          description: Short human-readable summary of what the monitor tracks.
        project_id:
          type: string
          description: Project that owns the monitor. Empty for workspace-wide monitors (admin-managed). Immutable after creation.
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/MonitorWidget'
          description: "Widgets rendered on the monitor, each carrying its own query and\n layout position."
        default_range:
          enum:
          - 5m
          - 15m
          - 30m
          - 1h
          - 6h
          - 12h
          - 1d
          - 7d
          - 14d
          - 30d
          - 60d
          - 90d
          type: string
          description: Default relative time range applied when the monitor opens.
        preset_key:
          type: string
          description: Preset this monitor was created from. Empty when built from scratch.
        created_at:
          type: string
          description: Time when the monitor was created.
          format: date-time
        updated_at:
          type: string
          description: Time when the monitor was last updated.
          format: date-time
        created_by_id:
          type: string
          description: User ID that created the monitor.
        updated_by_id:
          type: string
          description: User ID that last updated the monitor.
    CreateMonitorResponse:
      required:
      - monitor
      type: object
      properties:
        monitor:
          allOf:
          - $ref: '#/components/schemas/Monitor'
          description: Newly created monitor.
    MonitorPreset:
      required:
      - preset_key
      - display_name
      - description
      - kind
      - widgets
      type: object
      properties:
        preset_key:
          type: string
          description: "Stable identifier for the preset, e.g. `genai-overview` or\n `widget-cost-by-model`."
        display_name:
          type: string
          description: Human-readable preset name shown in galleries.
        description:
          type: string
          description: What the preset shows and when to use it.
        kind:
          enum:
          - dashboard
          - widget
          type: string
          description: Preset kind.
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/MonitorWidget'
          description: "Widgets the preset materializes into a create request. Widget\n presets carry exactly one entry."
        default_range:
          enum:
          - 5m
          - 15m
          - 30m
          - 1h
          - 6h
          - 12h
          - 1d
          - 7d
          - 14d
          - 30d
          - 60d
          - 90d
          type: string
          description: Default relative time range suggested by the preset.
    ListMonitorsResponse:
      required:
      - object
      - data
      - has_more
      type: object
      properties:
        object:
          type: string
          description: Object discriminator for list responses; always `list`.
        data:
          type: array
          items:
            $ref: '#/components/schemas/Monitor'
          description: Page of monitors, ordered newest first.
        has_more:
          type: boolean
          description: "Whether more monitors are available in the selected pagination\n direction."
    MonitorTelemetrySource:
      type: string
      enum:
      - MONITOR_TELEMETRY_SOURCE_TRACES
      - MONITOR_TELEMETRY_SOURCE_METRICS
      - MONITOR_TELEMETRY_SOURCE_LOGS
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: integer
          description: gRPC status code, when the service reports one.
        details:
          type: array
          items: {}
          description: Additional error details, when the service reports any.
      required:
      - message
    UpdateMonitorRequest:
      required: []
      type: object
      properties:
        display_name:
          type: string
          description: New workspace-unique display name. Omit to keep the current name.
        description:
          type: string
          description: New description. Omit to keep the current description.
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/MonitorWidget'
          description: "Replacement widget set. When update_mask contains `widgets`, this value\n replaces the full set and may be empty. Without update_mask, a non-empty\n array replaces all widgets while an empty or omitted array keeps them."
        default_range:
          type: string
          description: "New default relative time range. Omit to keep the current value unless\n update_mask contains `default_range`, which clears it."
        update_mask:
          type: string
          description: "Optional explicit update presence. Listed paths are replaced; omitting\n the mask preserves the legacy partial-update behavior."
          format: field-mask
    UpdateMonitorResponse:
      required:
      - monitor
      type: object
      properties:
        monitor:
          allOf:
          - $ref: '#/components/schemas/Monitor'
          description: Updated monitor.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
x-speakeasy-timeout: 600000