List Alerts

View as MarkdownEdit this pageReport an issueSet up docs MCP

GET/api/v2/alerts

Retrieves alerts for the authenticated team (paginated). Results are capped at limit (default and maximum 1000). When more records exist than are returned, meta.total exceeds data.length; clients with large collections must page with limit/offset to retrieve them all.

Authorizations

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Query parameters

limitoptionalinteger
Maximum number of alerts to return.

maximum: 1000, minimum: 1
Default: 1000
offsetoptionalinteger
Number of alerts to skip before returning results.

minimum: 0
Default: 0

Response

JSON

200

Successfully retrieved alerts

JSON

dataarray ofunknownrequired
List of alert objects.
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"
- chartConfigoptionalAlertLineChartConfigorAlertBarChartConfigorAlertNumberChartConfig
  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.
  
  3 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.
  
  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"
metaobjectrequired
Pagination metadata for this result page.
3 properties
- totalintegerrequired
  Total number of items matching the query, ignoring pagination.
  
  Example: 142
- limitintegerrequired
  Maximum number of items returned in this page.
  
  Example: 50
- offsetintegerrequired
  Number of items skipped before this page.
  
  Example: 100

List Alerts

curl --request GET \
  --url /api/v2/alerts \
  --header 'Authorization: Bearer <token>'

const url = '/api/v2/alerts';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

Response example

{
  "data": [
    {
      "id": "65f5e4a3b9e77c001a123456",
      "threshold": 100,
      "interval": "15m",
      "thresholdType": "above",
      "source": "tile",
      "state": "OK",
      "channel": {
        "type": "webhook",
        "webhookId": "65f5e4a3b9e77c001a789012"
      },
      "teamId": "65f5e4a3b9e77c001a345678",
      "tileId": "65f5e4a3b9e77c001a901234",
      "dashboardId": "65f5e4a3b9e77c001a567890",
      "displayName": "Checkout error spike",
      "tags": [
        "checkout",
        "p1"
      ],
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1000,
    "offset": 0
  }
}

{
  "message": "Unauthorized access. API key is missing or invalid."
}

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