Create Alert

POST/api/v2/alerts

Creates a new alert

Authorizations

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Request bodyJSON

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

Example: 100
interval1mor5mor15mor30mor1hor6h+2 morerequired
Evaluation interval for the alert.

Example: "1h"
thresholdTypeaboveorbeloworabove_exclusiveorbelow_or_equalorequalornot_equal+2 morerequired
Threshold comparison direction.

Example: "above"
dashboardIdoptionalstringor null
Dashboard ID for tile-based alerts.

Example: "65f5e4a3b9e77c001a567890"
tileIdoptionalstringor null
Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.

Example: "65f5e4a3b9e77c001a901234"
savedSearchIdoptionalstringor null
Saved search ID for saved_search alerts.

Example: "65f5e4a3b9e77c001a345678"
groupByoptionalstringor null
Group-by key for saved search alerts.

Example: "ServiceName"
chartConfigoptionalAlertLineChartConfigorAlertBarChartConfigorAlertStackedLineChartConfigorAlertNumberChartConfig
Chart configuration for inline alerts. Required when source is "inline" and rejected otherwise. Returned on single-alert responses (GET by ID, POST, PUT); the list endpoint omits it.
4 variants
One of the following:
AlertLineChartConfig
View AlertLineChartConfig schema →
3 properties
nameoptionalstring
Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

Example: "Error Rate Query"
whereoptionalstring
Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

maxLength: 10000
Example: "ServiceName:api"
whereLanguageoptionalsqlorlucene
Language of the chart-level "where" filter.

AlertBarChartConfig
View AlertBarChartConfig schema →
3 properties
nameoptionalstring
Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

Example: "Error Rate Query"
whereoptionalstring
Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

maxLength: 10000
Example: "ServiceName:api"
whereLanguageoptionalsqlorlucene
Language of the chart-level "where" filter.

AlertStackedLineChartConfig
View AlertStackedLineChartConfig schema →
3 properties
nameoptionalstring
Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

Example: "Error Rate Query"
whereoptionalstring
Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

maxLength: 10000
Example: "ServiceName:api"
whereLanguageoptionalsqlorlucene
Language of the chart-level "where" filter.

AlertNumberChartConfig
View AlertNumberChartConfig schema →
3 properties
nameoptionalstring
Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

Example: "Error Rate Query"
whereoptionalstring
Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

maxLength: 10000
Example: "ServiceName:api"
whereLanguageoptionalsqlorlucene
Language of the chart-level "where" filter.
thresholdMaxoptionalnumberor null
Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.

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

minimum: 0
Example: 2
scheduleStartAtoptionalstringor null
Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.

format: date-time
Example: "2026-02-08T10:00:00.000Z"
sourceoptionalsaved_searchortileorinline
Alert source type (tile-based or saved search).

Example: "tile"
channeloptionalAlertChannelWebhook
First notification channel, mirrored from "channels" for pre-multi-channel clients.
1 variants
One of the following:
AlertChannelWebhook
View AlertChannelWebhook schema →
2 properties
typewebhookrequired
Channel type. Must be "webhook" for webhook alerts.

webhookIdstringrequired
Webhook destination ID.

Example: "65f5e4a3b9e77c001a789012"
channelsoptionalarray ofAlertChannelWebhook
All notification channels to trigger when the alert fires or resolves.
1 variants
One of the following:
AlertChannelWebhook
View AlertChannelWebhook schema →
2 properties
typewebhookrequired
Channel type. Must be "webhook" for webhook alerts.

webhookIdstringrequired
Webhook destination ID.

Example: "65f5e4a3b9e77c001a789012"
nameoptionalstringor null
Alert name template (Handlebars), rendered as the notification title. When omitted, a default title is generated from the display name, value and threshold.

Example: "Errors for {{group}} hit {{value}}"
displayNameoptionalstringor null
Display name shown in the alerts list and in notification titles. Defaults to the name of the referenced saved search, dashboard tile, or inline chart when omitted or null.

maxLength: 512, minLength: 1
Example: "Checkout error spike"
tagsoptionalarray ofstringor null
Tags for the alert. Defaults to the tags of the referenced saved search or dashboard when omitted or null; inline alerts have no parent to inherit from and default to an empty list.

maxLength: 32
Example: ["checkout","p1"]
messageoptionalstringor null
Alert message template.

Example: "Test Alert Message"
noteoptionalstringor null
Freeform note for the alert. Supports markdown formatting.

maxLength: 4096, minLength: 1
Example: "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
numConsecutiveWindowsoptionalintegeror null
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.

minimum: 1
Example: 3

Response

JSON

200

Successfully created alert

JSON

dataoptionalobject
The alert object.
27 properties
- displayNamestringrequired
  The display name for the alert in the UI. Derived from the saved search name, dashboard tile name, or inline chartConfig name when not explicitly set.
  
  Example: "Checkout error spike"
- tagsarray ofstringrequired
  The tags for the alert. Derived from the tags of the referenced saved search or dashboard when not explicitly set; inline alerts default to an empty list.
  
  Example: ["checkout","p1"]
- dashboardIdoptionalstringor null
  Dashboard ID for tile-based alerts.
  
  Example: "65f5e4a3b9e77c001a567890"
- tileIdoptionalstringor null
  Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.
  
  Example: "65f5e4a3b9e77c001a901234"
- savedSearchIdoptionalstringor null
  Saved search ID for saved_search alerts.
  
  Example: "65f5e4a3b9e77c001a345678"
- groupByoptionalstringor null
  Group-by key for saved search alerts.
  
  Example: "ServiceName"
- chartConfigoptionalAlertLineChartConfigorAlertBarChartConfigorAlertStackedLineChartConfigorAlertNumberChartConfig
  Chart configuration for inline alerts. Required when source is "inline" and rejected otherwise. Returned on single-alert responses (GET by ID, POST, PUT); the list endpoint omits it.
  
  4 variants
  One of the following:
  AlertLineChartConfig
  View AlertLineChartConfig schema →
  3 properties
  nameoptionalstring
  Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.
  
  Example: "Error Rate Query"
  whereoptionalstring
  Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).
  
  maxLength: 10000
  Example: "ServiceName:api"
  whereLanguageoptionalsqlorlucene
  Language of the chart-level "where" filter.
  
  AlertBarChartConfig
  View AlertBarChartConfig schema →
  3 properties
  nameoptionalstring
  Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.
  
  Example: "Error Rate Query"
  whereoptionalstring
  Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).
  
  maxLength: 10000
  Example: "ServiceName:api"
  whereLanguageoptionalsqlorlucene
  Language of the chart-level "where" filter.
  
  AlertStackedLineChartConfig
  View AlertStackedLineChartConfig schema →
  3 properties
  nameoptionalstring
  Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.
  
  Example: "Error Rate Query"
  whereoptionalstring
  Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).
  
  maxLength: 10000
  Example: "ServiceName:api"
  whereLanguageoptionalsqlorlucene
  Language of the chart-level "where" filter.
  
  AlertNumberChartConfig
  View AlertNumberChartConfig schema →
  3 properties
  nameoptionalstring
  Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.
  
  Example: "Error Rate Query"
  whereoptionalstring
  Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).
  
  maxLength: 10000
  Example: "ServiceName:api"
  whereLanguageoptionalsqlorlucene
  Language of the chart-level "where" filter.
- thresholdoptionalnumber
  Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.
  
  Example: 100
- thresholdMaxoptionalnumberor null
  Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.
  
  Example: 500
- intervaloptional1mor5mor15mor30mor1hor6h+2 more
  Evaluation interval for the alert.
  
  Example: "1h"
- scheduleOffsetMinutesoptionalintegeror null
  Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).
  
  minimum: 0
  Example: 2
- scheduleStartAtoptionalstringor null
  Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.
  
  format: date-time
  Example: "2026-02-08T10:00:00.000Z"
- sourceoptionalsaved_searchortileorinline
  Alert source type (tile-based or saved search).
  
  Example: "tile"
- thresholdTypeoptionalaboveorbeloworabove_exclusiveorbelow_or_equalorequalornot_equal+2 more
  Threshold comparison direction.
  
  Example: "above"
- channeloptionalAlertChannelWebhook
  First notification channel, mirrored from "channels" for pre-multi-channel clients.
  
  1 variants
  One of the following:
  AlertChannelWebhook
  View AlertChannelWebhook schema →
  2 properties
  typewebhookrequired
  Channel type. Must be "webhook" for webhook alerts.
  
  webhookIdstringrequired
  Webhook destination ID.
  
  Example: "65f5e4a3b9e77c001a789012"
- channelsoptionalarray ofAlertChannelWebhook
  All notification channels to trigger when the alert fires or resolves.
  
  1 variants
  One of the following:
  AlertChannelWebhook
  View AlertChannelWebhook schema →
  2 properties
  typewebhookrequired
  Channel type. Must be "webhook" for webhook alerts.
  
  webhookIdstringrequired
  Webhook destination ID.
  
  Example: "65f5e4a3b9e77c001a789012"
- nameoptionalstringor null
  Alert name template (Handlebars), rendered as the notification title. When omitted, a default title is generated from the display name, value and threshold.
  
  Example: "Errors for {{group}} hit {{value}}"
- messageoptionalstringor null
  Alert message template.
  
  Example: "Test Alert Message"
- noteoptionalstringor null
  Freeform note for the alert. Supports markdown formatting.
  
  maxLength: 4096, minLength: 1
  Example: "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
- numConsecutiveWindowsoptionalintegeror null
  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.
  
  minimum: 1
  Example: 3
- idoptionalstring
  Unique alert identifier.
  
  Example: "65f5e4a3b9e77c001a123456"
- stateoptionalALERTorOKorINSUFFICIENT_DATAorDISABLEDorPENDING
  Current alert state.
  
  Example: "ALERT"
- teamIdoptionalstring
  Team identifier.
  
  Example: "65f5e4a3b9e77c001a345678"
- silencedoptionalobjector null
  Silencing metadata.
  
  3 properties
  byoptionalstringor null
  User ID who silenced the alert.
  
  Example: "65f5e4a3b9e77c001a234567"
  atoptionalstring
  Silence start timestamp.
  
  format: date-time
  Example: "2026-03-19T08:00:00.000Z"
  untiloptionalstring
  Silence end timestamp.
  
  format: date-time
  Example: "2026-03-20T08:00:00.000Z"
- executionErrorsoptionalarray ofobjector null
  Errors recorded during the most recent alert execution, if any.
  
  3 properties
  timestampstringrequired
  When the error occurred.
  
  format: date-time
  Example: "2026-04-17T12:00:00.000Z"
  typeQUERY_ERRORorQUERY_TIMEOUTorWEBHOOK_ERRORorINVALID_ALERTorUNKNOWNrequired
  Category of the error.
  
  Example: "QUERY_ERROR"
  messagestringrequired
  Human-readable error message.
  
  Example: "Query timed out after 30s"
- createdAtoptionalstringor null
  Creation timestamp.
  
  format: date-time
  Example: "2023-01-01T00:00:00.000Z"
- updatedAtoptionalstringor null
  Last update timestamp.
  
  format: date-time
  Example: "2023-01-01T00:00:00.000Z"

Create Alert

curl --request POST \
  --url /api/v2/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dashboardId": "65f5e4a3b9e77c001a567890",
  "tileId": "65f5e4a3b9e77c001a901234",
  "threshold": 100,
  "interval": "1h",
  "source": "tile",
  "thresholdType": "above",
  "channel": {
    "type": "webhook",
    "webhookId": "65f5e4a3b9e77c001a789012"
  },
  "name": "Error Spike Alert",
  "message": "Error rate has exceeded 100 in the last hour",
  "displayName": "Checkout error spike",
  "tags": [
    "checkout",
    "p1"
  ],
  "numConsecutiveWindows": 3
}
'

const url = '/api/v2/alerts';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    dashboardId: '65f5e4a3b9e77c001a567890',
    tileId: '65f5e4a3b9e77c001a901234',
    threshold: 100,
    interval: '1h',
    source: 'tile',
    thresholdType: 'above',
    channel: {type: 'webhook', webhookId: '65f5e4a3b9e77c001a789012'},
    name: 'Error Spike Alert',
    message: 'Error rate has exceeded 100 in the last hour',
    displayName: 'Checkout error spike',
    tags: ['checkout', 'p1'],
    numConsecutiveWindows: 3
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "/api/v2/alerts"

payload = {
    "dashboardId": "65f5e4a3b9e77c001a567890",
    "tileId": "65f5e4a3b9e77c001a901234",
    "threshold": 100,
    "interval": "1h",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
        "type": "webhook",
        "webhookId": "65f5e4a3b9e77c001a789012"
    },
    "name": "Error Spike Alert",
    "message": "Error rate has exceeded 100 in the last hour",
    "displayName": "Checkout error spike",
    "tags": ["checkout", "p1"],
    "numConsecutiveWindows": 3
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "data": {
    "dashboardId": "65f5e4a3b9e77c001a567890",
    "tileId": "65f5e4a3b9e77c001a901234",
    "savedSearchId": "65f5e4a3b9e77c001a345678",
    "groupBy": "ServiceName",
    "chartConfig": {
      "displayType": "line",
      "sourceId": "65f5e4a3b9e77c001a111111",
      "select": [
        {
          "aggFn": "count",
          "valueExpression": "Duration",
          "alias": "Request Duration",
          "level": 0.5,
          "where": "service:api",
          "whereLanguage": "sql",
          "metricName": "http.server.duration",
          "metricType": "sum",
          "periodAggFn": "delta",
          "numberFormat": {
            "output": "number",
            "mantissa": 2,
            "thousandSeparated": true,
            "average": false,
            "decimalBytes": false,
            "factor": 1,
            "currencySymbol": "$",
            "numericUnit": "bytes_iec",
            "unit": "ms"
          }
        }
      ],
      "groupBy": "host",
      "asRatio": false,
      "alignDateRangeToGranularity": true,
      "fillNulls": true,
      "fitYAxisToData": false,
      "numberFormat": {
        "output": "number",
        "mantissa": 2,
        "thousandSeparated": true,
        "average": false,
        "decimalBytes": false,
        "factor": 1,
        "currencySymbol": "$",
        "numericUnit": "bytes_iec",
        "unit": "ms"
      },
      "compareToPreviousPeriod": false,
      "seriesLimit": 5,
      "formulas": [
        {
          "expression": "A / (A + B) * 100",
          "alias": "Success rate %",
          "numberFormat": {
            "output": "number",
            "mantissa": 2,
            "thousandSeparated": true,
            "average": false,
            "decimalBytes": false,
            "factor": 1,
            "currencySymbol": "$",
            "numericUnit": "bytes_iec",
            "unit": "ms"
          }
        }
      ],
      "showOperandSeries": true,
      "name": "Error Rate Query",
      "where": "ServiceName:api",
      "whereLanguage": "sql"
    },
    "threshold": 100,
    "thresholdMax": 500,
    "interval": "1h",
    "scheduleOffsetMinutes": 2,
    "scheduleStartAt": "2026-02-08T10:00:00.000Z",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
      "type": "webhook",
      "webhookId": "65f5e4a3b9e77c001a789012"
    },
    "channels": [
      {
        "type": "webhook",
        "webhookId": "65f5e4a3b9e77c001a789012"
      }
    ],
    "name": "Errors for {{group}} hit {{value}}",
    "displayName": "Checkout error spike",
    "tags": [
      "checkout",
      "p1"
    ],
    "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",
    "state": "ALERT",
    "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",
        "type": "QUERY_ERROR",
        "message": "Query timed out after 30s"
      }
    ],
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
}

{
  "message": "NOT_FOUND: Alert not found"
}

{
  "message": "NOT_FOUND: Alert not found"
}

{
  "message": "NOT_FOUND: Alert not found"
}

Authorizations

Request bodyJSON

Response

200

401

403

500