Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Create an alert rule
Creates an alert rule in the project. The rule is evaluated every 60 seconds.
Target: a rule watches a SET of instances named by tags --
target = {kind: instance_selector, match: {key: value, ...}}, every pair must match. The
set is resolved inside the rule's project AT EVERY EVALUATION, so an instance tagged after
the rule was written is evaluated on the next tick with no further action, and an instance
whose tag is removed (or which is deleted) leaves the set: an alert it still holds open is
resolved once (event reason=target_deleted) and it stops being billed. Each matched
instance runs its OWN FIRING/OK cycle, its own forSeconds clock and its own
notification, and target.instances reports each one's state. A selector that matches
nothing is accepted: the rule is INSUFFICIENT_DATA until something is tagged.
Providers: instance_state -- a matched instance FIRES when it has been in the ERROR
state for condition.forSeconds and resolves (OK) when it leaves ERROR.
metric -- compares a VM metric (condition.metric: CPU %, memory %, disk MB/s and IOPS,
network Mbps, packets, errors, drops) aggregated over the window
(condition.aggregation: avg default, or max; per disk / NIC the worst device counts
-- the highest for gt/gte, the lowest for lt/lte) against condition.comparator +
condition.threshold (all three required). A matched instance whose monitoring is OFF is
SKIPPED, not refused: it is not evaluated and not billed, and it is counted in
target.monitoringDisabledCount. Switching monitoring off on an instance that is FIRING
sends its RESOLVED notification once (event reason=monitoring_disabled). Samples from
spans monitoring was off are ignored. provider is an open vocabulary.
Condition (window + for): windowSeconds is the aggregation window, at least 60,
default 300; forSeconds (default 0) is how long the condition must hold before FIRING.
Channels: channelIds are notification channels of the SAME project (at most 10);
they receive the FIRING and the RESOLVED notification, never a no-data one. Each
notification names the instance it is about.
Limit and billing: the unit is the rule x MATCHED INSTANCE -- a rule matching 20
instances uses 20 of the project's 50 (operator adjustable) and bills 20 units per hour
while it is enabled; firing costs nothing. Exceeding the limit is 409 QUOTA_EXCEEDED.
Errors: a channel outside the project is 404; an empty or malformed match is 422.
409 CONFLICT when the Idempotency-Key was already used for a different request (or for a
rule since deleted), or when a conflicting create landed concurrently.
Idempotency: Idempotency-Key is optional (recommended); replaying the same key with the
same body
returns 200 with the same rule. RBAC: MANAGE on the observability plane (owner, contributor).
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidapplication/json- body
Create body of an alert rule.
name*stringDisplay name of the rule.
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255provider*AlertRuleProviderSignal the rule evaluates. instance_state fires on an instance in ERROR; metric compares a VM metric of an instance with monitoring ON against a threshold. The vocabulary grows.
"instance_state""metric"target*The set of resources a rule watches, named by tags. Every key: value pair must match (AND); at least one pair is required -- an empty selector is 422, never "every instance".
condition?The window + for condition. Omitted values take their defaults (create) or keep their current value (update). metric, comparator and threshold are required for a metric rule and ignored for instance_state.
channelIds?array<string>Notification channel ids of the same project (default none).
items <= 10enabled?booleanWhether the rule is evaluated (default true).
Idempotent replay of an earlier create.
application/json- response
An alert rule of a project and its current evaluation state.
id*stringname*stringprovider*AlertRuleProviderSignal the rule evaluates. instance_state fires on an instance in ERROR; metric compares a VM metric of an instance with monitoring ON against a threshold. The vocabulary grows.
"instance_state""metric"target*A rule's tag selector and what it matches RIGHT NOW. matchedCount is resolved on every read, so it is true the moment an instance is tagged -- before the next evaluation has run -- while instances carries the per-instance state of the last evaluation.
condition*The effective window + for condition. The metric fields are present only on metric rules.
channelIds*array<string>Notification channels (same project) that receive FIRING and RESOLVED notifications.
enabled*booleanstate*AlertRuleStateEvaluation state. INSUFFICIENT_DATA before the first evaluation and while the signal has no data (e.g. the target was deleted).
"OK""FIRING""INSUFFICIENT_DATA"stateSince*stringISO-8601 time the rule entered its current state.
lastEvaluatedAt*|ISO-8601 time of the last evaluation; null before the first.
createdAt*stringcreatedBy*stringupdatedAt*stringcurl -X POST "https://example.com/scopes/string/observability/alert-rules" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "provider": "instance_state", "target": { "kind": "instance_selector", "match": { "property1": "string", "property2": "string" } } }'{ "id": "string", "name": "string", "provider": "instance_state", "target": { "kind": "instance_selector", "match": { "property1": "string", "property2": "string" }, "matchedCount": 0, "monitoringDisabledCount": 0, "instances": [ { "id": "string", "name": "string", "state": "OK", "stateSince": "string", "lastValue": 0, "lastEvaluatedAt": "string" } ] }, "condition": { "metric": "cpu.utilization", "aggregation": "avg", "comparator": "gt", "threshold": 0, "windowSeconds": 0, "forSeconds": 0 }, "channelIds": [ "string" ], "enabled": true, "state": "OK", "stateSince": "string", "lastEvaluatedAt": "string", "createdAt": "string", "createdBy": "string", "updatedAt": "string"}