OPopenobserve
Alerts

Create new alert

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.

post/api/v2/{org_id}/alerts

Request

Path parameters

org_idstring required

Organization name

Query parameters

folderstring

Folder ID for the alert. Authoritative: it overrides any folder_id in the body. The default folder is used when absent.

Request body

context_attributesobject nullable

Optional key-value attributes to include in alert notifications.

creates_incidentboolean

When true, this alert routes notifications through the incident system instead of sending direct alert notifications.

descriptionstring

Human-readable description of what this alert monitors.

destinationsstring[]

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.

enabledboolean

Whether the alert is active. Disabled alerts are not evaluated.

idstring nullable

Unique identifier for the alert. Auto-generated on creation.

incident_title_templatestring nullable

Incident title template; the generated title is used when no variable resolves.

is_real_timeboolean

If true, alert evaluates in real-time as data arrives. If false, alert runs on a schedule defined by trigger_condition.frequency.

keep_firing_forinteger

Seconds the condition must stay clear before the alert recovers. 0 recovers on the first clear evaluation.

last_edited_bystring nullable

Username who last edited the alert.

last_satisfied_atinteger nullable

Unix timestamp of when alert condition was last satisfied.

last_triggered_atinteger nullable

Unix timestamp of when alert was last triggered.

namestring

Human-readable name for the alert. Must be unique within the organization.

notify_on_recoveryboolean

Send one notification when this alert recovers; a multi-alert sends one per recovered group.

oncall_teamstring nullable

On-call team (a team id) this alert pages, taking precedence over ownership discovery. Omitted or null means "work the owner out from the identity dimensions", which is the normal case.

Validated at save against the on-call teams of the same org: a team id that names nothing routes nowhere, and a page that routes nowhere is silence rather than an error.

Save is a full replace, like tags — sending the alert back without this field clears the binding.

org_idstring

Organization ID. Usually set automatically from the request context.

ownerstring nullable

Username of the alert owner.

pending_period_secinteger
priorityinteger nullable

Priority 1..=5 (P1 = most urgent), Feature 2 / PT-1.

Mutable configuration; display + propagation only — it does not affect when the alert fires. Omitted = unset.

value_type is required because the enum serializes as an integer via serde try_from/into; without it the OpenAPI schema would advertise a string enum and lie about the payload.

recovery_destinationsstring[]

Where the recovery message goes. Empty = the firing's own destinations. Ticket closes are unaffected: a resolve must reach whatever the firing opened.

row_templatestring

Template for formatting individual rows in the alert message.

row_template_type'String' | 'Json'
runbook_urlstring nullable

Where the fix for this alert is written down.

Copied onto every on-call response record the alert opens, so whoever is woken is handed the link in the page instead of going to find it while the thing is on fire.

Validated at save: http:// or https:// with a host, or the save is refused. A malformed link stored today is a dead click at 3am, and the moment it is read is the worst possible moment to discover it.

Full replace, like oncall_team.

scheduler_job_presentboolean nullable

Whether a scheduler job exists for this alert (runtime status, not a stored field). Populated on the composite detail path; omitted otherwise.

stream_namestring

Name of the stream to monitor.

stream_type'logs' | 'metrics' | 'traces' | 'profiles' | 'service_graph' | 'enrichment_tables' | 'file_list' | 'metadata' | 'index'
suppress_repeatsboolean

Notify once per state change instead of on every firing evaluation. Enterprise only.

tagsstring[]

Selection tags (PT-6): prod, service:checkout. Normalized and validated on save; omitted when empty.

templatestring nullable

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.

tz_offsetinteger

Timezone offset in minutes. Negative values for western hemisphere.

updated_atinteger nullable

Unix timestamp of last modification.

workflowsstring[]

workflows to trigger when alert triggers

alert_type'all' | 'scheduled' | 'realtime' | 'anomaly_detection' | 'slo' | 'composite'

Filters the alert list by alert type (scheduled, realtime, anomaly detection, or all).

folder_idstring nullable

Deprecated. The destination folder is taken from the folder query parameter, which is what the permission check authorizes; the default folder is used when it is absent. A value here that disagrees with the query parameter is rejected with 400 rather than silently ignored.

Example request

{
  "description": "Fires when error count exceeds threshold in the specified time window",
  "destinations": [
    "slack-alerts",
    "pagerduty"
  ],
  "incident_title_template": "{service_name} errors on {host}",
  "name": "High Error Rate Alert",
  "oncall_team": "2f9K3mXQpLrTgYw8vN1cBzHd0Ae",
  "pending_period_sec": 10,
  "priority": 3,
  "runbook_url": "https://wiki.example.com/runbooks/checkout",
  "stream_name": "default",
  "tags": [
    "prod",
    "service:checkout"
  ],
  "workflows": [
    "abcde12345"
  ],
  "folder_id": "default"
}

Response

Success

codeinteger required
error_detailstring nullable
hintstring nullable

One-line guidance on how to fix the error (agent self-correction, D4).

idstring nullable
messagestring required
namestring nullable
suggestionsstring[] nullable

Closest valid alternatives for a mistyped field/function name.

trace_idstring nullable
warningsstring[] nullable

Problems with a request that succeeded anyway. Distinct from hint, which explains a failure: these accompany a 200, and the caller is entitled to have meant it.

Changes

No recorded changes to this operation across all 1 revision of this API.