Explore documentation
  1. Welcome to Uptime 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Connecting external calendars
    4. Advanced guide
  4. Incidents
    1. Get started
    2. Advanced guide
    3. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Uptime API
    1. Getting an API token
    2. Monitors
    3. Heartbeats
    4. On-call & incidents
      1. On-call schedule
      2. On-call schedule events
      3. On-call schedule 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. Escalate incident POST
        8. Remove incident DELETE
        9. Response attributes
      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

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

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 attributes

Next article

Get incident