List incidents

List all incidents with the option to filter incidents by monitor.

GET https://incidents.betterstack.com/api/v3/incidents

Query parameters

team_name

string

Filter incidents belonging to a specified team when using global API token.

from

date

Return only incidents from a certain date (format YYYY-MM-DD).

date

Return incidents until a certain date (format YYYY-MM-DD).

monitor_id

integer

Filter incidents belonging to a specified monitor.

heartbeat_id

integer

Filter incidents belonging to a specified heartbeat.

resolved

bool

List only resolved or unresolved incidents. When omitted both resolved and unresolved incidents are listed. Example: Use ?resolved=false to list active incidents.

acknowledged

bool

List only acknowledged or unacknowledged incidents. When omitted both acknowledged or unacknowledged incidents are listed.

metadata

nested

List incidents with matching metadata. Pass the metadata as nested query parameter. Example: Use ?metadata[key][][value]=value or ?metadata[key][][type]=User&metadata[key][][email]=user@example.com to list only incidents matching specified metadata value.

page

integer

The page number to return, starting with 1.

per_page

integer

Number of results per page. Defaults to 10, maximum 50.

Headers

Authorization

required string

Bearer $TOKEN

200

Returns a list of existing incidents, newest first.

Response body

{
  "data": [
    {
      "id": "25",
      "type": "incident",
      "attributes": {
        "name": "uptime homepage",
        "url": "https://uptime.betterstack.com/",
        "http_method": "get",
        "cause": "Status 404",
        "incident_group_id": null,
        "started_at": "2020-03-09T17:37:56.662Z",
        "acknowledged_at": null,
        "acknowledged_by": null,
        "resolved_at": null,
        "resolved_by": null,
        "status": "Started",
        "team_name": "Testing team",
        "response_content": "\n404 Not Found\n\nNot Found\nThe requested URL /fail was not found on this server.\n",
        "response_options": "{}",
        "regions": [
          "us",
          "eu",
          "as",
          "au"
        ],
        "response_url": null,
        "screenshot_url": null,
        "origin_url": null,
        "escalation_policy_id": null,
        "call": true,
        "sms": true,
        "email": true,
        "push": true,
        "critical_alert": false,
        "slack_channels": [
          "inc-20-03-09-uptime-homepage-not-found"
        ],
        "metadata": {
          "Origin": [
            {
              "type": "String",
              "value": "Monitor"
            }
          ],
          "Request duration": [
            {
              "type": "String",
              "value": "0.036304"
            }
          ],
          "Response code": [
            {
              "type": "String",
              "value": "404"
            }
          ]
        }
      },
      "relationships": {
        "monitor": {
          "data": {
            "id": "2",
            "type": "monitor"
          }
        }
      }
    },
    {
      "id": "23",
      "type": "incident",
      "attributes": {
        "name": "disk usage monitoring",
        "url": null,
        "http_method": null,
        "cause": "Disk space usage high",
        "incident_group_id": null,
        "started_at": "2020-03-04T13:30:45.583Z",
        "acknowledged_at": "2020-03-04T13:32:14.121Z",
        "acknowledged_by": "John Smith",
        "resolved_at": "2020-03-04T14:21:17.137Z",
        "resolved_by": "John Smith",
        "status": "Resolved",
        "team_name": "Testing team",
        "response_content": null,
        "response_options": null,
        "regions": null,
        "response_url": null,
        "screenshot_url": null,
        "origin_url": null,
        "escalation_policy_id": null,
        "call": false,
        "sms": false,
        "email": true,
        "push": true,
        "critical_alert": false,
        "slack_channels": [],
        "metadata": {
          "Origin": [
            {
              "type": "String",
              "value": "Datadog integration"
            }
          ]
        }
      },
      "relationships": {
        "webhook_integration": {
          "data": {
            "id": "30579",
            "type": "webhook_integration"
          }
        }
      }
    }
  ],
  "pagination": {
    "first": "https://incidents.betterstack.com/api/v3/incidents?page=1",
    "last": "https://incidents.betterstack.com/api/v3/incidents?page=4",
    "prev": null,
    "next": "https://incidents.betterstack.com/api/v3/incidents?page=2"
  }
}

Response attributes

string

The ID of the incident.

type

string

Always incident.

attributes.name

string

The name of the incident.

attributes.url

string or null

The URL the monitor checked, null for incidents not raised by a URL check.

attributes.http_method

string or null

The HTTP method of the check, such as get.

attributes.cause

string or null

What caused the incident, such as Status 500.

attributes.incident_group_id

integer or null

The ID of the group of similar incidents this incident belongs to, null when it isn't grouped.

attributes.started_at

string or null

When the incident started, as an ISO 8601 date-time. null while the incident is Unconfirmed.

attributes.acknowledged_at

string or null

When the incident was acknowledged, null until then.

attributes.acknowledged_by

string or null

The name of whoever acknowledged the incident, such as a team member or API.

attributes.resolved_at

string or null

When the incident was resolved, null until then.

attributes.resolved_by

string or null

The name of whoever resolved the incident.

attributes.status

string

The current status: Started, Acknowledged, Validating while the check is passing again during the recovery period, Resolved, or Unconfirmed while other regions are still confirming the failure. Listing returns only confirmed incidents.

attributes.team_name

string

The team the incident belongs to.

attributes.response_content

string or null

The response body that triggered the incident, when it's shorter than 500 characters. Longer bodies are linked in response_url instead.

attributes.response_options

string or null

Metadata of the response that triggered the incident, as a JSON string.

attributes.regions

array or null

The regions that ran the failing check: us, eu, as, or au.

attributes.response_url

string or null

A link to the response body that triggered the incident, when it's 500 characters or longer.

attributes.screenshot_url

string or null

A screenshot taken when the incident started.

attributes.origin_url

string or null

A link to the alert in the third-party tool that raised the incident.

attributes.escalation_policy_id

integer or null

The ID of the escalation policy alerting for this incident, null when none is set.

attributes.call

boolean

Whether the on-call person is called.

attributes.sms

boolean

Whether the on-call person gets an SMS.

attributes.email

boolean

Whether the on-call person gets an e-mail.

attributes.push

boolean

Whether the on-call person gets a push notification.

attributes.critical_alert

boolean

Whether the push notification is a critical alert that ignores the mute switch and Do Not Disturb mode. Devices that don't support critical alerts get a regular push notification.

attributes.slack_channels

array

The names of the Slack channels created for this incident by channel-type Slack integrations. Empty when there are none.

attributes.metadata

object

The incident's metadata, mapping each key to an array of values. Most incidents have an Origin key naming where they came from, such as Monitor or Datadog integration.

attributes.metadata.*[].type

string

The type of the value: String, User, Team, Policy, Schedule, Endpoint, Source, SlackIntegration, LinearIntegration, JiraIntegration, MicrosoftTeamsWebhook, ZapierWebhook, NativeWebhook, or PagerDutyWebhook.

attributes.metadata.*[].value

string

The text of a String value.

attributes.metadata.*[].item_id

integer

The ID of the item a value of any other type references.

attributes.metadata.*[].name

string

The name of the referenced item.

attributes.metadata.*[].email

string

The e-mail of the referenced user, only when type is User.

attributes.shared

boolean

Present and true when listing incidents with a token for one team and another team escalated the incident to yours.

attributes.ssl_certificate_expires_at

string

When the SSL certificate expires, as an ISO 8601 date-time. Present only on SSL certificate expiration incidents.

attributes.domain_expires_at

string

When the domain expires, as an ISO 8601 date-time. Present only on domain expiration incidents.

relationships.monitor.data.id

string

The ID of the monitor that triggered the incident, with type monitor. Present only for monitor incidents.

relationships.heartbeat.data.id

string

The ID of the heartbeat that triggered the incident, with type heartbeat. Present only for heartbeat incidents.

relationships.webhook_integration.data.id

string

The ID of the integration that triggered the incident, with type webhook_integration. Also present for incidents raised by a dashboard alert.

pagination.first

string

The URL of the first page. Read more about pagination.

pagination.last

string

The URL of the last page.

pagination.prev

string or null

The URL of the previous page, or null on the first page.

pagination.next

string or null

The URL of the next page, or null on the last page.

Example cURL

Time range Active incidents Metadata

Copied!

curl --request GET \
  --url "https://incidents.betterstack.com/api/v3/incidents" \
  --data-urlencode "from=2024-12-24" \
  --data-urlencode "to=2024-12-31" \
  --header 'Authorization: Bearer $TOKEN'

curl --request GET \
  --url "https://incidents.betterstack.com/api/v3/incidents" \
  --data-urlencode "resolved=false" \
  --header 'Authorization: Bearer $TOKEN'

curl --request GET \
  --url "https://incidents.betterstack.com/api/v3/incidents" \
  --data-urlencode "metadata[Group][][value]=HTTP checks" \
  --data-urlencode "metadata[Response code][][value]=500" \
  --data-urlencode "metadata[Response code][][value]=502" \
  --header 'Authorization: Bearer $TOKEN'

Remove severity group

Get incident

Explore documentation

List incidents

Example cURL

Please accept cookies