Alerts

Create Alert

Creates a new alert

post/api/v2/alerts

Request body

dashboardIdstring nullable

Dashboard ID for tile-based alerts.

tileIdstring nullable

Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.

savedSearchIdstring nullable

Saved search ID for saved_search alerts.

groupBystring nullable

Group-by key for saved search alerts.

thresholdnumber required

Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.

thresholdMaxnumber nullable

Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.

interval'1m' | '5m' | '15m' | '30m' | '1h' | '6h' | '12h' | '1d' required

Evaluation interval.

scheduleOffsetMinutesinteger nullable

Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).

scheduleStartAtstring date-time nullable

Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.

source'saved_search' | 'tile'

Alert source type.

Threshold comparison direction.

namestring nullable

Human-friendly alert name.

messagestring nullable

Alert message template.

notestring nullable

Freeform note for the alert. Supports markdown formatting.

numConsecutiveWindowsinteger nullable

Fire the alert only after its condition has been met for this many consecutive evaluation windows. While the condition is met but fewer than this many consecutive windows have violated, the alert is in the PENDING state.

Example request

{
  "dashboardId": "65f5e4a3b9e77c001a567890",
  "tileId": "65f5e4a3b9e77c001a901234",
  "savedSearchId": "65f5e4a3b9e77c001a345678",
  "groupBy": "ServiceName",
  "threshold": 100,
  "thresholdMax": 500,
  "scheduleOffsetMinutes": 2,
  "scheduleStartAt": "2026-02-08T10:00:00.000Z",
  "channel": {
    "webhookId": "65f5e4a3b9e77c001a789012"
  },
  "channels": [
    {
      "webhookId": "65f5e4a3b9e77c001a789012"
    }
  ],
  "name": "Test Alert",
  "message": "Test Alert Message",
  "note": "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook).",
  "numConsecutiveWindows": 3
}

Response

Successfully created alert

Example response

{
  "data": {
    "dashboardId": "65f5e4a3b9e77c001a567890",
    "tileId": "65f5e4a3b9e77c001a901234",
    "savedSearchId": "65f5e4a3b9e77c001a345678",
    "groupBy": "ServiceName",
    "threshold": 100,
    "thresholdMax": 500,
    "scheduleOffsetMinutes": 2,
    "scheduleStartAt": "2026-02-08T10:00:00.000Z",
    "channel": {
      "webhookId": "65f5e4a3b9e77c001a789012"
    },
    "channels": [
      {
        "webhookId": "65f5e4a3b9e77c001a789012"
      }
    ],
    "name": "Test Alert",
    "message": "Test Alert Message",
    "note": "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook).",
    "numConsecutiveWindows": 3,
    "id": "65f5e4a3b9e77c001a123456",
    "teamId": "65f5e4a3b9e77c001a345678",
    "silenced": {
      "by": "65f5e4a3b9e77c001a234567",
      "at": "2026-03-19T08:00:00.000Z",
      "until": "2026-03-20T08:00:00.000Z"
    },
    "executionErrors": [
      {
        "timestamp": "2026-04-17T12:00:00.000Z",
        "message": "Query timed out after 30s"
      }
    ],
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
}

Changes

Changed in 11 of the 60 revisions of this API.103746

Aug 21, 2026578ecc427dd82See the full diff
- ○
  added the new optional request property allOf[Alert]/channels
  new-optional-request-property
- ○
  added the optional property data/allOf[Alert]/channels to the response with the 200 status
  response-optional-property-added
Aug 11, 20260c6c6e7444061See the full diff
- ●
  added the new QUERY_TIMEOUT enum value to the data/allOf[subschema #2]/executionErrors/items/type response property for the response status 200
  response-property-enum-value-added
Jul 8, 20266f43817301231See the full diff
- ○
  added the non-success response with the status 403
  response-non-success-status-added
Jul 6, 2026e3a538a92f6712See the full diff
- ●
  added the new PENDING enum value to the data/allOf[subschema #2]/state response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property allOf[Alert]/numConsecutiveWindows
  new-optional-request-property
- ○
  added the optional property data/allOf[Alert]/numConsecutiveWindows to the response with the 200 status
  response-optional-property-added
May 13, 2026b3055248af4f2See the full diff
- ○
  added the new optional request property allOf[Alert]/note
  new-optional-request-property
- ○
  added the optional property data/allOf[Alert]/note to the response with the 200 status
  response-optional-property-added
Apr 17, 202649ba4aeaa9b41See the full diff
- ○
  added the optional property data/allOf[subschema #2]/executionErrors to the response with the 200 status
  response-optional-property-added
Apr 17, 202636a5514b174524See the full diff
- ●
  added the new between enum value to the data/allOf[Alert]/thresholdType response property for the response status 200
  response-property-enum-value-added
- ●
  added the new not_between enum value to the data/allOf[Alert]/thresholdType response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property allOf[Alert]/thresholdMax
  new-optional-request-property
- ○
  added the new between enum value to the request property allOf[Alert]/thresholdType
  request-property-enum-value-added
- ○
  added the new not_between enum value to the request property allOf[Alert]/thresholdType
  request-property-enum-value-added
- ○
  added the optional property data/allOf[Alert]/thresholdMax to the response with the 200 status
  response-optional-property-added
Apr 16, 2026dbf09188d84e44See the full diff
- ●
  added the new above_exclusive enum value to the data/allOf[Alert]/thresholdType response property for the response status 200
  response-property-enum-value-added
- ●
  added the new below_or_equal enum value to the data/allOf[Alert]/thresholdType response property for the response status 200
  response-property-enum-value-added
- ●
  added the new equal enum value to the data/allOf[Alert]/thresholdType response property for the response status 200
  response-property-enum-value-added
- ●
  added the new not_equal enum value to the data/allOf[Alert]/thresholdType response property for the response status 200
  response-property-enum-value-added
- ○
  added the new above_exclusive enum value to the request property allOf[Alert]/thresholdType
  request-property-enum-value-added
- ○
  added the new below_or_equal enum value to the request property allOf[Alert]/thresholdType
  request-property-enum-value-added
- ○
  added the new equal enum value to the request property allOf[Alert]/thresholdType
  request-property-enum-value-added
- ○
  added the new not_equal enum value to the request property allOf[Alert]/thresholdType
  request-property-enum-value-added
Mar 6, 2026d895d0cbdd274See the full diff
- ○
  added the new optional request property allOf[Alert]/scheduleOffsetMinutes
  new-optional-request-property
- ○
  added the new optional request property allOf[Alert]/scheduleStartAt
  new-optional-request-property
- ○
  added the optional property data/allOf[Alert]/scheduleOffsetMinutes to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/allOf[Alert]/scheduleStartAt to the response with the 200 status
  response-optional-property-added
Feb 2, 2026e856dc2f14173281See the full diff
- ▲
  added Alert subschema #2 to the request body allOf list
  request-body-all-of-added
- ▲
  the request's body type/format changed from object/ to /
  request-body-type-changed
- ▲
  the data response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ●
  removed the request property channel
  request-property-removed
- ●
  removed the request property dashboardId
  request-property-removed
- ●
  removed the request property groupBy
  request-property-removed
- ●
  removed the request property interval
  request-property-removed
- ●
  removed the request property message
  request-property-removed
- ●
  removed the request property name
  request-property-removed
- ●
  removed the request property savedSearchId
  request-property-removed
- ●
  removed the request property source
  request-property-removed
- ●
  removed the request property threshold
  request-property-removed
- ●
  removed the request property thresholdType
  request-property-removed
- ●
  removed the request property tileId
  request-property-removed
- ●
  removed the optional property data/channel from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/createdAt from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/dashboard from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/groupBy from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/interval from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/message from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/name from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/savedSearch from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/silenced from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/source from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/state from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/team from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/threshold from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/thresholdType from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/tileId from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/updatedAt from the response with the 200 status
  response-optional-property-removed
- ○
  added Alert subschema #2 to the data response property allOf list for the response status 200
  response-property-all-of-added

Full history (11 revisions)