Create an alert rule

The condition is checked when saved: its dataset and filter, its contact points, and a cost check (422 rule_too_expensive with readRows, readBytes and budget in the error's details, the only 422). 400 invalid_request with issues[] for every validation problem, each at its field's dotted path. 403 access_denied naming the missing action when the caller can't read what the condition reads (obs.metrics.query on the project for PromQL; obs.logs.search or obs.traces.search on the dataset). 409 quota_exceeded: obs.alertRules.perProject. 409 organization_deletion_pending. The answer's warnings: sampledData, noContactPoints. 404 while alerting isn't offered (the console hides Alerting then).

POST

https://obs.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/obs/alert-rules

View as Markdown

Authorization

apiKeyoptionalHTTP
oauthoptionalHTTP
sessionCookieoptionalAPI key in cookie

Path parameters

orgIdstringrequired
format: uuid
projectIdstringrequired
format: uuid

Header parameters

Idempotency-Keyoptionalstring
Makes a retry safe: the same key and request get the stored response.

pattern: ^[\x21-\x7e]{1,200}$

Request bodyJSONrequired

conditionobjectrequired
Exactly one of promql, logs and traces.
3 properties
- logsoptionalobject
  A logs or traces aggregate over [t − window, t); each group whose value satisfies the threshold is an active instance.
  
  6 properties
  aggregateobjectrequired
  One aggregation, as a dashboard panel's: {fn, field?}.
  
  2 properties
  fnstringrequired
  fieldoptionalunknown
  datasetstringrequired
  format: uuid
  thresholdobjectrequired
  2 properties
  op>or>=or<or<=or==or!=required
  valuenumberrequired
  windowstringrequired
  The aggregate's window, ending at the evaluation time: 1m to 15m in whole minutes.
  
  filteroptionalobject
  The dashboard panel's filter: logs' filters (LogFilters) or traces' (TraceFilters), kept as sent (stored as JSON: key order and number spelling may be normalized). Default {}.
  
  groupByoptionalarray ofobject
  At most 2 fields; at most 50 groups are evaluated (more is a rule error).
  
  1 properties
  fieldunknownrequired
- promqloptionalobject
  1 properties
  exprstringrequired
  A PromQL expression returning an instant vector, with its comparison: every series it returns is an active instance. Ranges, subquery ranges and offsets add up to at most 1h along any path; @ isn't allowed.
  
  maxLength: 8192
- tracesoptionalobject
  A logs or traces aggregate over [t − window, t); each group whose value satisfies the threshold is an active instance.
  
  6 properties
  aggregateobjectrequired
  One aggregation, as a dashboard panel's: {fn, field?}.
  
  2 properties
  fnstringrequired
  fieldoptionalunknown
  datasetstringrequired
  format: uuid
  thresholdobjectrequired
  2 properties
  op>or>=or<or<=or==or!=required
  valuenumberrequired
  windowstringrequired
  The aggregate's window, ending at the evaluation time: 1m to 15m in whole minutes.
  
  filteroptionalobject
  The dashboard panel's filter: logs' filters (LogFilters) or traces' (TraceFilters), kept as sent (stored as JSON: key order and number spelling may be normalized). Default {}.
  
  groupByoptionalarray ofobject
  At most 2 fields; at most 50 groups are evaluated (more is a rule error).
  
  1 properties
  fieldunknownrequired
namestringrequired
maxLength: 100, minLength: 1
annotationsoptionalmap ofstring
Templates (Prometheus's alerting template language, without query, range or template; at most 4 KiB each, 16 in all), rendered per instance with $labels and $value.
contactPointsoptionalarray ofstring
0 to 10 contact point IDs of the project. Default none (the rule still evaluates and keeps state).

format: uuid
descriptionoptionalstring
maxLength: 1000
enabledoptionalboolean
Off: the rule isn't evaluated and has no instances. Default true.
foroptionalstring
How long the condition must hold before an instance fires: 0 to 24h in whole minutes. Default 0.
keepFiringForoptionalstring
How long a firing instance keeps firing after the condition stops holding: 0 to 24h in whole minutes. Default 0.
labelsoptionalmap ofstring
Static labels on every instance (at most 32). alertname, ezgh_* and __* are reserved.
noDataoptionalokoralertingornoData
Logs and traces conditions whose aggregate returns no groups: ok (nothing active), alerting (one active instance) or noData (one instance in the noData state). Default noData. PromQL ignores it: use absent().
notifyOnResolveoptionalboolean
Notify when instances resolve. Default true.
onErroroptionalerrororok
A rule error (the engine refuses the query, more than 1,000 instances, a budget exceeded): error puts the rule in the error state and notifies; ok records it without notifying. Default error. EZGH's own failures never notify.
repeatIntervaloptionalstring
How often a still-firing rule notifies again: 5m to 7d. Default 4h.

Returns

201

The alert rule.

JSON

conditionobjectrequired
Exactly one of promql, logs and traces.
3 properties
- logsoptionalobject
  A logs or traces aggregate over [t − window, t); each group whose value satisfies the threshold is an active instance.
  
  6 properties
  aggregateobjectrequired
  One aggregation, as a dashboard panel's: {fn, field?}.
  
  2 properties
  fnstringrequired
  fieldoptionalunknown
  datasetstringrequired
  format: uuid
  thresholdobjectrequired
  2 properties
  op>or>=or<or<=or==or!=required
  valuenumberrequired
  windowstringrequired
  The aggregate's window, ending at the evaluation time: 1m to 15m in whole minutes.
  
  filteroptionalobject
  The dashboard panel's filter: logs' filters (LogFilters) or traces' (TraceFilters), kept as sent (stored as JSON: key order and number spelling may be normalized). Default {}.
  
  groupByoptionalarray ofobject
  At most 2 fields; at most 50 groups are evaluated (more is a rule error).
  
  1 properties
  fieldunknownrequired
- promqloptionalobject
  1 properties
  exprstringrequired
  A PromQL expression returning an instant vector, with its comparison: every series it returns is an active instance. Ranges, subquery ranges and offsets add up to at most 1h along any path; @ isn't allowed.
  
  maxLength: 8192
- tracesoptionalobject
  A logs or traces aggregate over [t − window, t); each group whose value satisfies the threshold is an active instance.
  
  6 properties
  aggregateobjectrequired
  One aggregation, as a dashboard panel's: {fn, field?}.
  
  2 properties
  fnstringrequired
  fieldoptionalunknown
  datasetstringrequired
  format: uuid
  thresholdobjectrequired
  2 properties
  op>or>=or<or<=or==or!=required
  valuenumberrequired
  windowstringrequired
  The aggregate's window, ending at the evaluation time: 1m to 15m in whole minutes.
  
  filteroptionalobject
  The dashboard panel's filter: logs' filters (LogFilters) or traces' (TraceFilters), kept as sent (stored as JSON: key order and number spelling may be normalized). Default {}.
  
  groupByoptionalarray ofobject
  At most 2 fields; at most 50 groups are evaluated (more is a rule error).
  
  1 properties
  fieldunknownrequired
contactPointsarray ofstringrequired
0 to 10 contact point IDs of the project. Default none (the rule still evaluates and keeps state).

format: uuid
createdAtstringrequired
UTC, millisecond precision: 2026-10-02T10:20:00.000Z.

format: date-time
createdByobjectrequired
2 properties
- idstringrequired
- typestringrequired
  user or bot (org-api's principal type).
enabledbooleanrequired
Off: the rule isn't evaluated and has no instances. Default true.
forstringrequired
How long the condition must hold before an instance fires: 0 to 24h in whole minutes. Default 0.
idstringrequired
format: uuid
keepFiringForstringrequired
How long a firing instance keeps firing after the condition stops holding: 0 to 24h in whole minutes. Default 0.
kindstringrequired
The condition's kind: promql, logs or traces.
namestringrequired
maxLength: 100, minLength: 1
noDataokoralertingornoDatarequired
Logs and traces conditions whose aggregate returns no groups: ok (nothing active), alerting (one active instance) or noData (one instance in the noData state). Default noData. PromQL ignores it: use absent().
notifyOnResolvebooleanrequired
Notify when instances resolve. Default true.
onErrorerrororokrequired
A rule error (the engine refuses the query, more than 1,000 instances, a budget exceeded): error puts the rule in the error state and notifies; ok records it without notifying. Default error. EZGH's own failures never notify.
projectIdstringrequired
format: uuid
repeatIntervalstringrequired
How often a still-firing rule notifies again: 5m to 7d. Default 4h.
resourceNamestringrequired
slugstringrequired
statusobjectrequired
A rule's evaluation state.
10 properties
- countsobjectrequired
  3 properties
  firingintegerrequired
  noDataintegerrequired
  pendingintegerrequired
- degradedbooleanrequired
  Evaluations are delayed by an EZGH issue (late data or storage unavailable): state is held and nothing resolves or notifies about it.
- degradedSincestring | nullrequired
  format: date-time
- errorstring | nullrequired
  The last evaluation's rule error, or null.
- errorSincestring | nullrequired
  format: date-time
- lastDurationMsinteger | nullrequired
- lastEvaluatedAtstring | nullrequired
  format: date-time
- statestringrequired
  ok, pending, firing, noData, error or disabled (off, or its organization is being deleted). More may be added.
- stateSincestring | nullrequired
  When the rule entered its state (as obs-alerts recorded it); null when not known yet, or disabled.
  
  format: date-time
- warningsarray ofstringrequired
  sampledData, noContactPoints. More codes may be added.
updatedAtstringrequired
UTC, millisecond precision: 2026-10-02T10:20:00.000Z.

format: date-time
updatedByobjectrequired
2 properties
- idstringrequired
- typestringrequired
  user or bot (org-api's principal type).
versionintegerrequired
annotationsoptionalmap ofstring
Templates (Prometheus's alerting template language, without query, range or template; at most 4 KiB each, 16 in all), rendered per instance with $labels and $value.
descriptionoptionalstring
maxLength: 1000
labelsoptionalmap ofstring
Static labels on every instance (at most 32). alertname, ezgh_* and __* are reserved.
warningsoptionalarray ofstring
Create and update answers only: sampledData (a traces condition on a dataset with tail sampling sees only kept spans) and noContactPoints (the rule notifies no one).

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.