---
title: List incidents
description: Returns a list of incidents for a status page.
url: https://docs.honeybadger.io/api/v3/incidents/list-status-page-incidents/
---

API v3 is in preview

Endpoints and response shapes [can change before general availability](https://docs.honeybadger.io/api/v3/#preview). API v2 is unchanged.

GET `https://app.honeybadger.io/v3/status_pages/{status_page_id}/incidents`

[Required scope](https://docs.honeybadger.io/api/v3/authentication/#scopes) `incidents:read`

Returns a list of incidents for a status page.

Example request

```sh
curl "https://app.honeybadger.io/v3/status_pages/$STATUS_PAGE_ID/incidents" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN"
```

## Parameters

### Path parameters

| Field | Type | Description |
| - | - | - |
| `status_page_id` required | string | Status page ID. |

### Query parameters

| Field | Type | Description |
| - | - | - |
| `limit` | integer | Maximum items to return. Values above 100 are treated as 100. Default: `25`. Min 1, max 100. |
| `before` | string | Cursor for fetching older items. |
| `after` | string | Cursor for fetching newer items. |

## Responses

### 200 Success

Example payload

```json
{
  "data": [
    {
      "id": "In3pKr",
      "status_page_id": "Sp7bMq",
      "title": "Database connectivity issues",
      "retro_should_notify": true,
      "retro_notify_message": null,
      "build_type": "current",
      "current_status": "maintenance_scheduled",
      "current_severity": "problem_detected",
      "start_at": "2026-01-01T00:00:00Z",
      "closed_at": "2026-01-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "updates": [
        {
          "id": "Iu6tMn",
          "incident_id": "In3pKr",
          "message": "We have identified the cause and are rolling back.",
          "status": "maintenance_scheduled",
          "severity": "problem_detected",
          "start_at": "2026-01-01T00:00:00Z",
          "should_notify": true,
          "notified_at": "2026-01-01T00:00:00Z",
          "created_at": "2026-01-01T00:00:00Z",
          "updated_at": "2026-01-01T00:00:00Z"
        }
      ],
      "links": {
        "web": "https://app.honeybadger.io/projects/Xk9mZp"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "has_older": true,
    "has_newer": true,
    "oldest_cursor": "eyJ0IjoxNzA0MDY3MjAwLCJpIjoiTm04cFF4In0",
    "newest_cursor": "eyJ0IjoxNzA0MTUzNjAwLCJpIjoiWGs5bVpwIn0"
  },
  "links": {
    "self": "/v3/status_pages/Sp7bMq/incidents?limit=25",
    "older": "/v3/status_pages/Sp7bMq/incidents?before=eyJ0IjoxNzA0MDY3MjAwMTIzNDU2LCJpIjoiRHAyeU5rIn0&limit=25",
    "newer": "/v3/status_pages/Sp7bMq/incidents?after=eyJ0IjoxNzA0MTUzNjAwMTIzNDU2LCJpIjoiRHA4d1FzIn0&limit=25"
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `data` required | array\<object> | |
| `data[].id` required | string | |
| `data[].status_page_id` required | string | ID of the status page. |
| `data[].title` required | string | Incident title. |
| `data[].retro_should_notify` required | boolean | For a retroactive incident, whether to announce it once on the status page's connected accounts. |
| `data[].retro_notify_message` required | string \| null | The announcement sent when `retro_should_notify` is true. |
| `data[].build_type` required | string | How the incident was opened. `current` is happening now, `retroactive` records something already over, `scheduled_maintenance` is planned. Only a scheduled\_maintenance incident may have updates starting in the future. Allowed values: `current`, `retroactive`, `scheduled_maintenance`. |
| `data[].current_status` | string \| null | Status of the update in effect now. Derived from the updates. An incident's status. Allowed values: `maintenance_scheduled`, `in_maintenance`, `maintenance_complete`, `investigating`, `identified`, `resolving`, `monitoring`, `resolved`. |
| `data[].current_severity` | string \| null | Severity of the update in effect now. Derived from the updates. An incident's severity. Allowed values: `problem_detected`, `degraded_performance`, `partial_outage`, `outage`, `operational`. |
| `data[].start_at` | date-time \| null | When the incident starts. Derived from the updates. |
| `data[].closed_at` | date-time \| null | When the incident closed, or null while it is open. Derived from the updates: it is set once an update reaches resolved or maintenance\_complete. |
| `data[].created_at` | date-time | When the incident was created. |
| `data[].updated_at` | date-time | When the incident was last updated. |
| `data[].updates` required | array\<object> | The incident's thread, newest first. Always at least one update. |
| `data[].updates[].id` required | string | |
| `data[].updates[].incident_id` required | string | ID of the incident. |
| `data[].updates[].message` | string \| null | The update's prose. |
| `data[].updates[].status` required | string | An incident's status. Allowed values: `maintenance_scheduled`, `in_maintenance`, `maintenance_complete`, `investigating`, `identified`, `resolving`, `monitoring`, `resolved`. |
| `data[].updates[].severity` required | string | An incident's severity. Allowed values: `problem_detected`, `degraded_performance`, `partial_outage`, `outage`, `operational`. |
| `data[].updates[].start_at` | date-time | When the update takes effect. A future time schedules it. |
| `data[].updates[].should_notify` | boolean \| null | Whether the update is announced on the status page's connected accounts. |
| `data[].updates[].notified_at` | date-time \| null | When the announcement was sent. |
| `data[].updates[].created_at` | date-time | When the update was posted. |
| `data[].updates[].updated_at` | date-time | When the update was last changed. |
| `data[].links` required | object | Links into the Honeybadger web UI. |
| `data[].links.web` required | uri | The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have `links`. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on. |
| `pagination` | object | Pagination for a time-ordered collection. |
| `pagination.limit` required | integer | Maximum items per page. Min 1, max 100. |
| `pagination.has_older` required | boolean | Whether older items exist. When true, follow `links.older`. |
| `pagination.has_newer` required | boolean | Whether newer items exist. When true, follow `links.newer`. |
| `pagination.oldest_cursor` | string \| null | Cursor for the oldest item on this page. Pass it back unchanged as `before`. Absent or null on collections that page on a timestamp rather than a cursor; use `links.older` instead. |
| `pagination.newest_cursor` | string \| null | Cursor for the newest item on this page. Pass it back unchanged as `after`. Absent or null on collections that page on a timestamp rather than a cursor, and on one-directional collections; use `links.newer` instead. |
| `links` | object | Navigation links for a time-ordered collection. Each link is a root-relative path (`/v3/...`); resolve it against the API host. |
| `links.self` required | uri-reference | This page. |
| `links.older` | string \| null | Page of older items, or null when none exist. |
| `links.newer` | string \| null | Page of newer items, or null when none exist. Always null on one-directional collections, which are documented as such. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

## Errors

### 400 Bad Request

A query parameter is malformed or outside its allowed values. `error.details` names the parameter.

Example payload

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "unmapped must be true or false",
    "details": [
      {
        "field": "unmapped",
        "message": "must be true or false"
      }
    ]
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 401 Unauthorized

The credential is missing, invalid, expired or revoked (`unauthorized`), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: unsupported\_auth\_scheme (Sent as HTTP basic, which v3 does not accept)

```json
{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: credential\_in\_query (Sent as the \`auth\_token\` query parameter)

```json
{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 403 Forbidden

The credential isn’t allowed to do this. `error.code` says why. An account or project the credential doesn’t cover is 404 `not_found`, not 403.

Example payload: access\_denied (The credential isn't allowed to do this to this record)

```json
{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: insufficient\_scope (The credential lacks the permission this endpoint requires)

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: requires\_user\_token (The endpoint records who acted, and an account token has nobody)

```json
{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: project\_restricted (A project-restricted credential cannot create a project)

```json
{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 404 Not Found

Resource not found

Example payload

```json
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 422 Unprocessable Content

No path names the account, so the API token has to. This is returned when the token covers more than one account and the account a request applies to cannot be determined. Use a token bound to a single account.

Example payload

```json
{
  "error": {
    "code": "ambiguous_account",
    "message": "This credential covers more than one account, so the account a request applies to is ambiguous. Use a token bound to a single account."
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)