Explore documentation
  1. Welcome to Uptime 👋
  2. Frequently Asked Questions
  3. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  4. On-call scheduling and alerting
    1. Get started
    2. Sending alerts to Slack ↗
    3. Connecting external calendars
    4. Advanced guide
  5. Incidents
    1. Get started
    2. Advanced guide
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Integrations
    1. Integrating with Better Stack
  8. Team and account management
    1. Team management
    2. Account settings
    3. Audit logs
    4. Migrating to pay as you go
  9. Uptime API
    1. Get an API token
    2. Monitors
    3. Heartbeats
    4. On-call & incidents
      1. On-call calendar
      2. On-call calendar events
      3. On-call calendar rotations
      4. Escalation policies
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
        1. List incidents GET
        2. Get incident GET
        3. List incident timeline GET
        4. Create incident POST
        5. Acknowledge incident POST
        6. Resolve incident POST
        7. Remove incident DELETE
        8. Response params
      9. Comments
    5. Status pages
    6. Metadata
    7. Integrations

List incidents

List all incidents with the option to filter incidents by monitor. This endpoint supports pagination with default of 10 per page and maximum of 50.

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

Query parameters

from
date

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

to
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.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns list of existing incidents

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,
        "metadata": {
          "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,
        "metadata": {}
      },
      "relationships": {
        "webhook_integration": {
          "data": {
            "id": "30579",
            "type": "webhook_integration"
          }
        }
      }
    }
  ],
  "pagination": {
    "first": "https://uptime.betterstack.com/api/v3/incidents?page=1",
    "last": "https://uptime.betterstack.com/api/v3/incidents?page=4",
    "prev": null,
    "next": "https://uptime.betterstack.com/api/v3/incidents?page=2"
  }
}

Example cURL

Time range Active incidents Metadata 
curl --request GET \
  --url "https://uptime.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://uptime.betterstack.com/api/v3/incidents" \
  --data-urlencode "resolved=false" \
  --header 'Authorization: Bearer $TOKEN'
curl --request GET \
  --url "https://uptime.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'

Previous article

Response params

Next article

Get incident