# List incidents

List all incidents with the option to filter incidents by monitor. This endpoint [supports pagination](https://betterstack.com/docs/uptime/api/pagination/) with default of 10 per page and maximum of 50.

[endpoint]
base_url = "https://uptime.betterstack.com"
path = "/api/v3/incidents"
method = "GET"

[[query_param]]
name = "team_name"
description = "Filter incidents belonging to a specified team when using [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token)."
required = false
type = "string"

[[query_param]]
name = "from"
description = "Return only incidents from a certain date (format YYYY-MM-DD)."
required = false
type = "date"

[[query_param]]
name = "to"
description = "Return incidents until a certain date (format YYYY-MM-DD)."
required = false
type = "date"

[[query_param]]
name = "monitor_id"
description = "Filter incidents belonging to a specified monitor."
required = false
type = "integer"

[[query_param]]
name = "heartbeat_id"
description = "Filter incidents belonging to a specified heartbeat."
required = false
type = "integer"

[[query_param]]
name = "resolved"
description = "List only resolved or unresolved incidents. When omitted both resolved and unresolved incidents are listed. Example: Use `?resolved=false` to list active incidents."
required = false
type = "bool"

[[query_param]]
name = "acknowledged"
description = "List only acknowledged or unacknowledged incidents. When omitted both acknowledged or unacknowledged incidents are listed."
required = false
type = "bool"

[[query_param]]
name = "metadata"
description = "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."
required = false
type = "nested"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''Returns list of existing incidents'''
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": {
          "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": {}
      },
      "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"
  }
}'''
[/responses]

#### Example cURL 

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

[info]
#### Looking for the details of a specific parameter?
Explore [the list of all incidents API parameters](https://betterstack.com/docs/uptime/api/incidents-api-response-params/).
[/info]