> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# List Incidents

> Returns a paginated list of incidents for your organization.

Retrieves all incidents belonging to your organization. Results are returned in reverse chronological order (newest first) and can be filtered by status, severity, or date range. Use the `cursor` parameter to paginate through large result sets.

## Query parameters

<ParamField query="status" type="string">
  Filter by incident status. One of `investigating`, `identified`, `monitoring`, or `resolved`.
</ParamField>

<ParamField query="severity" type="string">
  Filter by incident severity. One of `critical`, `high`, `medium`, or `low`.
</ParamField>

<ParamField query="from" type="string">
  Return incidents created on or after this date. ISO 8601 date format (e.g. `2025-01-01`).
</ParamField>

<ParamField query="to" type="string">
  Return incidents created on or before this date. ISO 8601 date format (e.g. `2025-12-31`).
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of incidents to return per page. Must be between `1` and `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned by the previous response as `nextCursor`. Omit to fetch the first page.
</ParamField>

## Response

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="incidents" type="Incident[]" required>
      Array of incident objects for the current page.

      <Expandable title="Incident properties">
        <ResponseField name="id" type="string" required>
          Unique identifier for the incident (UUID).
        </ResponseField>

        <ResponseField name="orgId" type="string" required>
          The organization this incident belongs to.
        </ResponseField>

        <ResponseField name="title" type="string" required>
          Short title describing the incident.
        </ResponseField>

        <ResponseField name="severity" type="string" required>
          Severity level: `critical`, `high`, `medium`, or `low`.
        </ResponseField>

        <ResponseField name="status" type="string" required>
          Current lifecycle status: `investigating`, `identified`, `monitoring`, or `resolved`.
        </ResponseField>

        <ResponseField name="affectedComponents" type="array of object" required>
          Components affected by this incident. Each entry has `id` and `name`. Empty array if none.
        </ResponseField>

        <ResponseField name="createdAt" type="string" required>
          ISO 8601 timestamp of when the incident was created.
        </ResponseField>

        <ResponseField name="updatedAt" type="string" required>
          ISO 8601 timestamp of when the incident was last updated.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nextCursor" type="string | null" required>
      Cursor to pass as `cursor` on your next request to fetch the following page. `null` when there are no more results.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Code             | Description                               |
| ------ | ---------------- | ----------------------------------------- |
| `401`  | `not_authorized` | Missing or invalid API key.               |
| `500`  | `server_error`   | An unexpected error occurred on our side. |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.scaling.cloud/v1/incidents?status=investigating&severity=critical&limit=10" \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "incidents": [
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "orgId": "org_01HX4K9MNPQRST",
          "title": "Payment service elevated error rate",
          "severity": "critical",
          "status": "investigating",
          "affectedComponents": [
            { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
          ],
          "createdAt": "2025-04-07T08:23:11.000Z",
          "updatedAt": "2025-04-07T08:23:11.000Z"
        },
        {
          "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "orgId": "org_01HX4K9MNPQRST",
          "title": "API gateway latency spike",
          "severity": "high",
          "status": "investigating",
          "affectedComponents": [],
          "createdAt": "2025-04-07T07:55:42.000Z",
          "updatedAt": "2025-04-07T07:55:42.000Z"
        }
      ],
      "nextCursor": "eyJpZCI6ImIyYzNkNGU1LWY2YTctODkwMSJ9"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "statusCode": 401,
    "type": "not_authorized_error",
    "code": "not_authorized",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 500 theme={null}
  {
    "statusCode": 500,
    "type": "invalid_error",
    "code": "server_error",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```
</ResponseExample>