OpenObserve Alerts API
Alerts retrieval & management operations
OpenAPI Specification
openapi: 3.1.0
info:
title: openobserve Actions Alerts API
description: OpenObserve API documents [https://openobserve.ai/docs/](https://openobserve.ai/docs/)
contact:
name: OpenObserve
url: https://openobserve.ai/
email: hello@zinclabs.io
license:
name: AGPL-3.0
identifier: AGPL-3.0
version: 0.90.0
tags:
- name: Alerts
description: Alerts retrieval & management operations
paths:
/api/v2/{org_id}/alerts:
get:
tags:
- Alerts
summary: List organization alerts
description: Retrieves a list of all alerts in the organization with filtering and pagination options. Shows alert summaries including names, status, folder organization, and basic configuration details for monitoring and management purposes.
operationId: ListAlerts
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
- name: folder
in: query
description: Optional folder ID filter parameter.
required: false
schema:
type: string
style: form
- name: stream_type
in: query
description: Optional stream type filter parameter.
required: false
schema:
$ref: '#/components/schemas/StreamType'
style: form
- name: stream_name
in: query
description: 'Optional stream name filter parameter.
This parameter is only used if `stream_type` is also provided.'
required: false
schema:
type: string
style: form
- name: alert_name_substring
in: query
description: Optional case-insensitive name substring filter parameter.
required: false
schema:
type: string
style: form
- name: owner
in: query
description: Optional owner user filter parameter.
required: false
schema:
type: string
style: form
- name: enabled
in: query
description: Optional enabled filter parameter.
required: false
schema:
type: boolean
style: form
- name: page_size
in: query
description: 'The optional number of alerts to retrieve. If not set then all alerts
that match the query parameters will be returned.'
required: false
schema:
type: integer
format: int64
minimum: 0
style: form
- name: page_idx
in: query
description: 'The optional page index. If not set then defaults to `0`.
This parameter is only used if `page_size` is also set.'
required: false
schema:
type: integer
format: int64
minimum: 0
style: form
- name: alert_type
in: query
description: 'Optional alert type filter: `all` (default), `scheduled`, `realtime`,
or `anomaly_detection`.'
required: false
schema:
$ref: '#/components/schemas/AlertTypeFilter'
style: form
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
description: HTTP response body for `ListAlerts` endpoint.
required:
- list
properties:
list:
type: array
items:
$ref: '#/components/schemas/ListAlertsResponseBodyItem'
security:
- Authorization: []
x-o2-ratelimit:
module: Alerts
operation: list
x-o2-mcp:
description: List all alerts
category: alerts
summary_fields:
- name
- stream_name
- stream_type
- enabled
- is_real_time
- folder_id
- folder_name
post:
tags:
- Alerts
summary: Create new alert
description: Creates a new alert with specified conditions, triggers, and notifications. Users can define custom queries, thresholds, and notification destinations to monitor their data and receive timely alerts when conditions are met.
operationId: CreateAlert
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
- name: folder
in: query
description: Folder ID (Required if alert folder is not the default folder)
required: false
schema:
type: string
requestBody:
description: Alert data
content:
application/json:
schema:
allOf:
- oneOf:
- type: object
description: 'Alert configuration for monitoring streams and triggering notifications.
An alert watches a stream (logs, metrics, or traces) using SQL or PromQL queries,
and sends notifications to configured destinations when trigger conditions are met.'
properties:
context_attributes:
type:
- object
- 'null'
description: Optional key-value attributes to include in alert notifications.
additionalProperties:
type: string
propertyNames:
type: string
creates_incident:
type: boolean
description: 'When true, this alert routes notifications through the incident system
instead of sending direct alert notifications.'
deduplication:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/DeduplicationConfig'
description: Optional deduplication configuration to prevent alert spam.
description:
type: string
description: Human-readable description of what this alert monitors.
example: Fires when error count exceeds threshold in the specified time window
destinations:
type: array
items:
type: string
description: 'List of destination names to notify when alert fires.
Destinations must be pre-configured in the system.
Accepts either `destinations` or `alert_destinations` as the JSON field name.'
example:
- slack-alerts
- pagerduty
enabled:
type: boolean
description: Whether the alert is active. Disabled alerts are not evaluated.
id:
type:
- string
- 'null'
description: Unique identifier for the alert. Auto-generated on creation.
readOnly: true
is_real_time:
type: boolean
description: 'If true, alert evaluates in real-time as data arrives.
If false, alert runs on a schedule defined by trigger_condition.frequency.'
last_edited_by:
type:
- string
- 'null'
description: Username who last edited the alert.
readOnly: true
last_satisfied_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp of when alert condition was last satisfied.
readOnly: true
last_triggered_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp of when alert was last triggered.
readOnly: true
name:
type: string
description: Human-readable name for the alert. Must be unique within the organization.
example: High Error Rate Alert
org_id:
type: string
description: Organization ID. Usually set automatically from the request context.
owner:
type:
- string
- 'null'
description: Username of the alert owner.
query_condition:
$ref: '#/components/schemas/QueryCondition'
description: 'Query configuration: SQL query or PromQL expression to evaluate.'
row_template:
type: string
description: Template for formatting individual rows in the alert message.
row_template_type:
$ref: '#/components/schemas/RowTemplateType'
description: Format type for the row template.
stream_name:
type: string
description: Name of the stream to monitor.
example: default
stream_type:
$ref: '#/components/schemas/StreamType'
description: 'Type of stream to monitor: logs, metrics, or traces.'
template:
type:
- string
- 'null'
description: 'Optional template name. When specified, this template is used for all
destinations instead of destination-level templates. This allows using
different templates for different alerts while reusing the same destinations.'
trigger_condition:
$ref: '#/components/schemas/TriggerCondition'
description: 'Trigger configuration: when and how often to evaluate, thresholds.'
tz_offset:
type: integer
format: int32
description: Timezone offset in minutes. Negative values for western hemisphere.
updated_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp of last modification.
readOnly: true
description: The alert configuration. All fields from Alert are flattened into this request body.
- type: object
properties:
alert_type:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/AlertTypeFilter'
description: 'Discriminates the alert type. Defaults to scheduled alert when absent.
Set to `"anomaly_detection"` to create an anomaly detection config instead.'
anomaly_config:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/AnomalyAlertFields'
description: Anomaly-detection-specific fields (nested object).
folder_id:
type:
- string
- 'null'
description: 'Optional folder ID indicating the folder in which to create the alert.
If omitted the alert will be created in the default folder.'
example: default
description: "HTTP request body for `CreateAlert` endpoint.\n\nCreates a new alert with the specified configuration. The alert monitors\na stream (logs, metrics, or traces) and triggers notifications when conditions are met.\n\n## Example\n\n```json\n{\n \"name\": \"High Error Rate Alert\",\n \"stream_type\": \"logs\",\n \"stream_name\": \"default\",\n \"is_real_time\": false,\n \"query_condition\": {\n \"type\": \"sql\",\n \"sql\": \"SELECT count(*) as count FROM \\\"default\\\" WHERE level = 'error'\"\n },\n \"trigger_condition\": {\n \"period\": 15,\n \"operator\": \">=\",\n \"threshold\": 100,\n \"frequency\": 5,\n \"frequency_type\": \"minutes\",\n \"silence\": 60\n },\n \"destinations\": [\"slack-alerts\"],\n \"enabled\": true,\n \"description\": \"Alert when error count exceeds 100 in 15 minutes\"\n}\n```"
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
'400':
description: Error
content:
application/json:
schema:
default: null
security:
- Authorization: []
x-o2-mcp:
description: 'Create a new alert rule with flexible query options. IMPORTANT: Alert name must use snake_case (no spaces/special chars like :,#,?,&,%,/,quotes), destinations array is required with valid destination names. QueryCondition supports 3 query types: (1) Custom - uses conditions, aggregation, vrl_function, search_event_type, multi_time_range; (2) SQL - uses sql, vrl_function, search_event_type; (3) PromQL - uses promql, promql_condition, multi_time_range'
category: alerts
x-o2-ratelimit:
module: Alerts
operation: create
/api/v2/{org_id}/alerts/bulk/enable:
post:
tags:
- Alerts
summary: Enable or disable alert in bulk
description: Toggles the active status of alerts to enable or disable its monitoring and notification functionality in bulk. When disabled, the alert will stop evaluating conditions and sending notifications until re-enabled.
operationId: EnableAlertBulk
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
- name: value
in: query
description: Set to `true` to enable the alert or `false` to disable the alert.
required: true
schema:
type: boolean
style: form
requestBody:
description: Alert id list
content:
application/json:
schema:
type: object
required:
- ids
properties:
ids:
type: array
items:
type: string
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
'404':
description: NotFound
content:
application/json:
schema:
default: null
'500':
description: Failure
content:
application/json:
schema:
default: null
security:
- Authorization: []
x-o2-ratelimit:
module: Alerts
operation: update
x-o2-mcp:
enabled: false
/api/v2/{org_id}/alerts/generate_sql:
post:
tags:
- Alerts
summary: Generate SQL from alert query parameters
description: Generates a SQL query string based on alert query parameters including stream, aggregations, and conditions. This endpoint is useful for testing alert queries and understanding the SQL that will be executed.
operationId: GenerateSql
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
requestBody:
description: SQL generation parameters
content:
application/json:
schema:
type: object
description: HTTP request body for `GenerateSql` endpoint.
required:
- stream_name
- stream_type
- query_condition
properties:
query_condition:
$ref: '#/components/schemas/QueryCondition'
description: 'Query condition containing aggregation and WHERE conditions
The conditions field within QueryCondition supports both V1 and V2 formats'
stream_name:
type: string
description: Stream name to query
example: default
stream_type:
$ref: '#/components/schemas/StreamType'
description: Type of stream (logs, metrics, traces, etc.)
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
description: HTTP response body for `GenerateSql` endpoint.
required:
- sql
properties:
metadata:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/GenerateSqlMetadata'
description: Optional metadata about the generated query
sql:
type: string
description: The generated SQL query string
example: SELECT * FROM "my_stream" WHERE field > 100
'400':
description: Bad request - invalid parameters
content:
application/json:
schema:
type: object
'500':
description: Internal server error
content:
application/json:
schema:
type: object
security:
- Authorization: []
x-o2-mcp:
description: Generate SQL from natural language
category: alerts
x-o2-ratelimit:
module: Alerts
operation: generate_sql
/api/v2/{org_id}/alerts/move:
patch:
tags:
- Alerts
summary: Move alerts between folders
description: Moves one or more alerts from their current folder to a specified destination folder. Helps organize alerts into logical groups and manage access permissions when using role-based access control.
operationId: MoveAlerts
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
- name: folder
in: query
description: From Folder ID (Required if RBAC enabled)
required: false
schema:
type: string
requestBody:
description: Identifies alerts and the destination folder
content:
application/json:
schema:
type: object
description: HTTP request body for `MoveAlerts` endpoint.
required:
- alert_ids
- dst_folder_id
properties:
alert_ids:
type: array
items:
type: string
description: IDs of the alerts to move.
anomaly_config_ids:
type: array
items:
type: string
description: 'IDs of anomaly detection configs to move. Defaults to empty when not
provided. Callers should always supply this to avoid per-ID DB lookups.'
dst_folder_id:
type: string
description: Indicates the folder to which alerts should be moved.
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
'404':
description: NotFound
content:
application/json:
schema:
default: null
'500':
description: Failure
content:
application/json:
schema:
default: null
security:
- Authorization: []
x-o2-mcp:
description: Move alerts to another folder
category: alerts
x-o2-ratelimit:
module: Alerts
operation: update
/api/v2/{org_id}/alerts/{alert_id}:
get:
tags:
- Alerts
summary: Get alert details
description: Retrieves detailed information about a specific alert including its configuration, conditions, triggers, notification settings, and current status. Useful for viewing and understanding existing alert setups.
operationId: GetAlert
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
- name: alert_id
in: path
description: Alert ID
required: true
schema:
type: string
- name: folder
in: query
description: Folder ID (Required if RBAC enabled)
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Alert'
description: HTTP response body for `GetAlert` endpoint.
'404':
description: NotFound
content:
application/json:
schema:
default: null
security:
- Authorization: []
x-o2-mcp:
description: Get alert details by ID
category: alerts
x-o2-ratelimit:
module: Alerts
operation: get
put:
tags:
- Alerts
summary: Update alert configuration
description: Updates an existing alert's configuration including conditions, queries, thresholds, notification destinations, and scheduling. Allows users to modify alert behavior and settings as monitoring requirements change.
operationId: UpdateAlert
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
- name: alert_id
in: path
description: Alert ID
required: true
schema:
type: string
- name: folder
in: query
description: Folder ID (Required if RBAC enabled)
required: false
schema:
type: string
requestBody:
description: Alert data
content:
application/json:
schema:
allOf:
- oneOf:
- type: object
description: 'Alert configuration for monitoring streams and triggering notifications.
An alert watches a stream (logs, metrics, or traces) using SQL or PromQL queries,
and sends notifications to configured destinations when trigger conditions are met.'
properties:
context_attributes:
type:
- object
- 'null'
description: Optional key-value attributes to include in alert notifications.
additionalProperties:
type: string
propertyNames:
type: string
creates_incident:
type: boolean
description: 'When true, this alert routes notifications through the incident system
instead of sending direct alert notifications.'
deduplication:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/DeduplicationConfig'
description: Optional deduplication configuration to prevent alert spam.
description:
type: string
description: Human-readable description of what this alert monitors.
example: Fires when error count exceeds threshold in the specified time window
destinations:
type: array
items:
type: string
description: 'List of destination names to notify when alert fires.
Destinations must be pre-configured in the system.
Accepts either `destinations` or `alert_destinations` as the JSON field name.'
example:
- slack-alerts
- pagerduty
enabled:
type: boolean
description: Whether the alert is active. Disabled alerts are not evaluated.
id:
type:
- string
- 'null'
description: Unique identifier for the alert. Auto-generated on creation.
readOnly: true
is_real_time:
type: boolean
description: 'If true, alert evaluates in real-time as data arrives.
If false, alert runs on a schedule defined by trigger_condition.frequency.'
last_edited_by:
type:
- string
- 'null'
description: Username who last edited the alert.
readOnly: true
last_satisfied_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp of when alert condition was last satisfied.
readOnly: true
last_triggered_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp of when alert was last triggered.
readOnly: true
name:
type: string
description: Human-readable name for the alert. Must be unique within the organization.
example: High Error Rate Alert
org_id:
type: string
description: Organization ID. Usually set automatically from the request context.
owner:
type:
- string
- 'null'
description: Username of the alert owner.
query_condition:
$ref: '#/components/schemas/QueryCondition'
description: 'Query configuration: SQL query or PromQL expression to evaluate.'
row_template:
type: string
description: Template for formatting individual rows in the alert message.
row_template_type:
$ref: '#/components/schemas/RowTemplateType'
description: Format type for the row template.
stream_name:
type: string
description: Name of the stream to monitor.
example: default
stream_type:
$ref: '#/components/schemas/StreamType'
description: 'Type of stream to monitor: logs, metrics, or traces.'
template:
type:
- string
- 'null'
description: 'Optional template name. When specified, this template is used for all
destinations instead of destination-level templates. This allows using
different templates for different alerts while reusing the same destinations.'
trigger_condition:
$ref: '#/components/schemas/TriggerCondition'
description: 'Trigger configuration: when and how often to evaluate, thresholds.'
tz_offset:
type: integer
format: int32
description: Timezone offset in minutes. Negative values for western hemisphere.
updated_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp of last modification.
readOnly: true
description: Alert configuration fields (used for scheduled/realtime alerts).
- type: object
properties:
alert_type:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/AlertTypeFilter'
description: 'Discriminates the alert type. When `"anomaly_detection"`, delegates to the
anomaly config update path.'
anomaly_config:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/UpdateAnomalyAlertFields'
description: 'Anomaly-detection-specific fields to update (partial — only supplied fields
are changed).'
description: 'HTTP request body for `UpdateAlert` endpoint.
Updates an existing alert. Provide the full alert configuration — this replaces
the existing alert entirely (not a partial update). The request body is the same
structure as Alert.
For anomaly detection configs, set `alert_type = "anomaly_detection"` and supply
anomaly-specific fields directly at the top level (flat). Only fields present in
the request body will be updated (partial update semantics for anomaly fields).'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
'400':
description: Error
content:
application/json:
schema:
default: null
security:
- Authorization: []
x-o2-mcp:
description: Update an existing alert
category: alerts
x-o2-ratelimit:
module: Alerts
operation: update
delete:
tags:
- Alerts
summary: Delete alert
description: Permanently removes an alert and all its configurations including conditions, triggers, and notification settings. This action cannot be undone and will stop all monitoring and notifications for the deleted alert.
operationId: DeleteAlert
parameters:
- name: org_id
in: path
description: Organization name
required: true
schema:
type: string
- name: alert_id
in: path
description: Alert ID
required: true
schema:
type: string
- name: folder
in: query
description: Folder ID (Required if RBAC enabled)
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
'500':
description: Failure
content:
application/json:
schema:
default: null
security:
- Authorization: []
x-o2-ratelimit:
module: Alerts
operation: delete
x-o2-mcp:
description: Delete an alert by ID
category: alerts
requires_confirmation: true
/api/v2/{org_id}/alerts/{alert_id}/clone:
post:
tags:
- Alerts
summary: Clone an alert or anomaly detection config
description: Creates a
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openobserve/refs/heads/main/openapi/openobserve-alerts-api-openapi.yml