---
title: "Create a monitor"
method: POST
path: "/v2/monitors"
tags: ["Monitors"]
---

# Create a monitor

`POST /v2/monitors`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/monitors`
- Auth: HTTP bearer

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.

## Request body

- CreateMonitorRequest
  - `display_name` string, required: Workspace-unique display name.
  - `description` string: Short human-readable summary of what the monitor tracks.
  - `project_id` string: Project that should own the monitor. Omit to create a workspace-wide monitor (requires admin access).
  - `widgets` MonitorWidget[]: Widgets to render on the monitor. Empty creates a valid blank monitor.
    - `widget_id` string, required: Widget identifier, unique within the monitor. Provide your own or leave empty to have the server assign one.
    - `type` 'timeseries' | 'toplist' | 'table' | 'bignumber' | 'donut' | 'breakdown', required: Widget rendering type.
    - `title` string, required: Title shown in the widget header.
    - `queries` MonitorWidgetQuery[], required: The one query feeding the widget. It maps onto QueryTelemetry; the viewer's time range, time zone, and the query mode derived from the widget type are supplied at render time.
      - `source` 'MONITOR_TELEMETRY_SOURCE_TRACES' | 'MONITOR_TELEMETRY_SOURCE_METRICS' | 'MONITOR_TELEMETRY_SOURCE_LOGS'
      - `metric` string, required: Source-owned metric identifier. Static `genai.*` trace metrics are validated when saved; runtime metrics, logs, and raw trace aggregates are validated by the caller-scoped telemetry capability/query service.
      - `operation` string: Source-owned aggregation operation advertised by telemetry capabilities.
      - `group_by` string[]: Reporting dimensions to break down by. Valid dimensions depend on the metric; validated when the monitor is saved.
      - `filters` MonitorFilter[]: Reporting filters combined with AND.
        - `field` string, required: Reporting dimension to filter on. Valid fields depend on the metric; validated when the monitor is saved.
        - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'contains' | 'exists' | 'not_exists', required: Predicate operator. `eq` and `neq` accept exactly one value; `in` and `not_in` accept 1-100 values.
        - `values` string[], required: Values compared against the selected field.
      - `grain` 'auto' | 'minute' | 'hour' | 'day': Requested bucket grain for timeseries widgets.
      - `limit` integer: Row cap. Zero uses the reporting default. For toplist widgets this is the top-N group count.
      - `additional_computes` MonitorWidgetCompute[]: Extra computes for breakdown widgets, rendered as columns after the primary `metric`/`operation`, which drives sorting. They share the query's source, grouping, and filters.
        - `metric` string, required: Source-owned metric identifier.
        - `operation` string, required: Source-owned aggregation operation advertised by telemetry capabilities.
    - `display` MonitorWidgetDisplay
      - `visualization` 'lines' | 'bars' | 'area': Chart style for timeseries widgets.
      - `unit` 'count' | 'cost' | 'duration' | 'percent' | 'bytes': Unit used for axis and value formatting.
      - `sort` 'desc' | 'asc': Value ordering for toplist, table and breakdown widgets.
      - `show_overall` boolean: When true, toplist, table and breakdown widgets also show the overall total across all groups for the window.
      - `target` number, double: Optional threshold line rendered on timeseries widgets.
      - `decimals` integer: Decimal places used when formatting values.
      - `show_others` boolean: When true, toplist and donut widgets show the combined value of groups outside the configured limit.
      - `show_percentages` boolean: When true, toplist and donut widget values are shown as a percentage of the overall total.
    - `layout` MonitorWidgetLayout, required
      - `x` integer, required: Column offset in grid units.
      - `y` integer, required: Row offset in grid units.
      - `w` integer, required: Width in grid units.
      - `h` integer, required: Height in grid units.
  - `default_range` string: Default relative time range applied when the monitor opens.
  - `preset_key` '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': Known preset used to create the monitor. Empty when built from scratch.

## Response `200`

OK

- CreateMonitorResponse
  - `monitor` Monitor, required
    - `monitor_id` string, required: Unique monitor identifier assigned by ORQ, for example `monitor_01H...`. Use this value in retrieve, update, and delete requests.
    - `display_name` string, required: Workspace-unique display name.
    - `description` string, required: Short human-readable summary of what the monitor tracks.
    - `project_id` string, required: Project that owns the monitor. Empty for workspace-wide monitors (admin-managed). Immutable after creation.
    - `widgets` MonitorWidget[], required: Widgets rendered on the monitor, each carrying its own query and layout position.
      - `widget_id` string, required: Widget identifier, unique within the monitor. Provide your own or leave empty to have the server assign one.
      - `type` 'timeseries' | 'toplist' | 'table' | 'bignumber' | 'donut' | 'breakdown', required: Widget rendering type.
      - `title` string, required: Title shown in the widget header.
      - `queries` MonitorWidgetQuery[], required: The one query feeding the widget. It maps onto QueryTelemetry; the viewer's time range, time zone, and the query mode derived from the widget type are supplied at render time.
        - `source` 'MONITOR_TELEMETRY_SOURCE_TRACES' | 'MONITOR_TELEMETRY_SOURCE_METRICS' | 'MONITOR_TELEMETRY_SOURCE_LOGS'
        - `metric` string, required: Source-owned metric identifier. Static `genai.*` trace metrics are validated when saved; runtime metrics, logs, and raw trace aggregates are validated by the caller-scoped telemetry capability/query service.
        - `operation` string: Source-owned aggregation operation advertised by telemetry capabilities.
        - `group_by` string[]: Reporting dimensions to break down by. Valid dimensions depend on the metric; validated when the monitor is saved.
        - `filters` MonitorFilter[]: Reporting filters combined with AND.
          - `field` string, required: Reporting dimension to filter on. Valid fields depend on the metric; validated when the monitor is saved.
          - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'contains' | 'exists' | 'not_exists', required: Predicate operator. `eq` and `neq` accept exactly one value; `in` and `not_in` accept 1-100 values.
          - `values` string[], required: Values compared against the selected field.
        - `grain` 'auto' | 'minute' | 'hour' | 'day': Requested bucket grain for timeseries widgets.
        - `limit` integer: Row cap. Zero uses the reporting default. For toplist widgets this is the top-N group count.
        - `additional_computes` MonitorWidgetCompute[]: Extra computes for breakdown widgets, rendered as columns after the primary `metric`/`operation`, which drives sorting. They share the query's source, grouping, and filters.
          - `metric` string, required: Source-owned metric identifier.
          - `operation` string, required: Source-owned aggregation operation advertised by telemetry capabilities.
      - `display` MonitorWidgetDisplay
        - `visualization` 'lines' | 'bars' | 'area': Chart style for timeseries widgets.
        - `unit` 'count' | 'cost' | 'duration' | 'percent' | 'bytes': Unit used for axis and value formatting.
        - `sort` 'desc' | 'asc': Value ordering for toplist, table and breakdown widgets.
        - `show_overall` boolean: When true, toplist, table and breakdown widgets also show the overall total across all groups for the window.
        - `target` number, double: Optional threshold line rendered on timeseries widgets.
        - `decimals` integer: Decimal places used when formatting values.
        - `show_others` boolean: When true, toplist and donut widgets show the combined value of groups outside the configured limit.
        - `show_percentages` boolean: When true, toplist and donut widget values are shown as a percentage of the overall total.
      - `layout` MonitorWidgetLayout, required
        - `x` integer, required: Column offset in grid units.
        - `y` integer, required: Row offset in grid units.
        - `w` integer, required: Width in grid units.
        - `h` integer, required: Height in grid units.
    - `default_range` '5m' | '15m' | '30m' | '1h' | '6h' | '12h' | '1d' | '7d' | '14d' | '30d' | '60d' | '90d': Default relative time range applied when the monitor opens.
    - `preset_key` string, required: Preset this monitor was created from. Empty when built from scratch.
    - `created_at` string, date-time, required: Time when the monitor was created.
    - `updated_at` string, date-time, required: Time when the monitor was last updated.
    - `created_by_id` string, required: User ID that created the monitor.
    - `updated_by_id` string, required: User ID that last updated the monitor.

## Other responses

- `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-23** `0b4e519a544f`: 1 info
  - endpoint added
- **2026-10-23** `732aed62833a`: 1 breaking
  - api path removed without deprecation
- **2026-10-22** `4f826b2c3a0e`: 1 info
  - endpoint added
- **2026-10-22** `8f0dc569f247`: 1 breaking
  - api path removed without deprecation
- **2026-10-21** `08b800d640e6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/monitors/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)