# List incidents

`GET https://evohub.io/api/v1/incidents`

Part of the [On-Call API](https://docs.evohub.io/oncall.md) reference · operationId `listIncidents`.

Lists the organization's incidents, newest first. Paged with `limit`
(default 50) and `offset`; there is no total count.

**Permission (API-key scope):** `oncall:incident:read`.

## Authorization

Any one of:

- `bearerAuth` (oncall:incident:read)
- `apiKeyHeader` (oncall:incident:read)

Where:

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Query parameters

- `status` (IncidentStatus, one of `investigating`, `identified`, `monitoring`, `resolved`): Only incidents in this status.
- `limit` (integer, default `50`, min 0): Page size. 0 or omitted means 50; more than 500 returns 500. Anything but a whole number of 0 or more is refused (400 `VALIDATION_FAILED`, field `limit`).
- `offset` (integer, default `0`, min 0): How many items to skip. Anything but a whole number of 0 or more is refused (400 `VALIDATION_FAILED`, field `offset`).

## Responses

### 200 — A page of incidents.

Content type: `application/json`

Type: `object`

- `data` (array of Incident, required)
  - `id` (string, required)
  - `org_id` (string)
  - `number` (integer, required): Sequential number within the organization.
  - `title` (string, required)
  - `summary` (string)
  - `severity` (IncidentSeverity, required, one of `none`, `minor`, `major`, `critical`)
  - `status` (IncidentStatus, required, one of `investigating`, `identified`, `monitoring`, `resolved`)
  - `commander_id` (string)
  - `started_at` (string (date-time), required)
  - `identified_at` (string (date-time))
  - `resolved_at` (string (date-time))
  - `timeline` (array of IncidentTimelineEntry): The timeline entries, oldest first. Only in the answer of Get an incident.
    - `id` (string)
    - `incident_id` (string)
    - `author_id` (string)
    - `status` (string): The incident's status when the entry was written.
    - `message` (string)
    - `created_at` (string (date-time))
  - `created_at` (string (date-time))
  - `updated_at` (string (date-time))
  - `version` (integer): Goes up by one on every edit of the title, summary, severity or commander (not on acknowledge or resolve). Send it with an update to refuse the edit if someone else changed the incident first.
- `success` (boolean, required, value `true`)

### 400 — `limit` or `offset` is not a whole number of 0 or more (`VALIDATION_FAILED`).

Content type: `application/json`

Type: `ValidationError`

- `error` (object, required)
  - `code` (string, required, value `VALIDATION_FAILED`)
  - `message` (string, required)
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.
  - `details` (array of object, required)
    - `field` (string)
    - `message` (string)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 429 — Too many requests (`RATE_LIMITED`). Wait `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 500 — Something went wrong on EvoHub's side (`INTERNAL_ERROR`). Retry later.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

## Example request

```bash
curl -X GET 'https://evohub.io/api/v1/incidents' \
  -H 'Authorization: Bearer <TOKEN>'
```