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

# Alert Intelligence API

> Programmatically retrieve escalated alerts and alert statistics from Traversal using the V1 Alert Intelligence API.

<Note>
  **Private Beta.** The Alert Intelligence API is in private beta and is enabled per-organization. The
  shape of these endpoints may change before general availability. If you'd like access, contact your
  Traversal point of contact or [support@traversal.com](mailto:support@traversal.com).
</Note>

The Alert Intelligence API exposes the results of Traversal's alert triage — the alerts it escalated for
investigation and aggregate statistics about alert volume and noise reduction over a time range. This is
the same alert data that powers the Alert Intelligence view in the Traversal web application.

All endpoints require authentication — see [Authentication](/api/authentication) to create an API key.
For base URL, error envelope, and generic status codes, see the [API overview](/api/overview).

<Note>
  The Alert Intelligence API must be explicitly enabled for your organization. Requests from an
  organization without access return `403 Forbidden`.
</Note>

## Required roles

API keys inherit the role of the user who created them. Both endpoints require at least the `member`
role; a request from an underprivileged key returns `403 Forbidden`.

| Endpoint | Minimum role |
| - | - |
| `GET /v1/alerts/escalations` — List escalations | `member` |
| `GET /v1/alerts/statistics` — Get statistics | `member` |

## Time-range filtering

Both endpoints accept optional `start_time` and `end_time` query parameters that filter on when each
alert fired (`fired_at`). Both must be **timezone-aware ISO-8601** timestamps (e.g.
`2026-05-27T00:00:00Z`); a naive timestamp returns `400`. When both are provided, `end_time` must be
strictly greater than `start_time`.

## List escalations

`GET /v1/alerts/escalations`

Returns alerts that Traversal escalated for investigation, most recent first, with their root-cause
summaries. Paginated.

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `start_time` | `string` | Inclusive lower bound on when the alert fired (timezone-aware ISO-8601). |
| `end_time` | `string` | Exclusive upper bound on when the alert fired (timezone-aware ISO-8601). |
| `page` | `integer` | 1-indexed page number. Defaults to `1`. |
| `limit` | `integer` | Page size. Defaults to `50`, maximum `100`. |

### Example request

```bash theme={null}
curl "https://api.traversal.com/v1/alerts/escalations?start_time=2026-05-01T00:00:00Z&end_time=2026-06-01T00:00:00Z&limit=20" \
  -H "Authorization: Bearer $TRAVERSAL_API_KEY"
```

### Example response

```json theme={null}
{
  "escalations": [
    {
      "alert_name": "High CPU on checkout-api",
      "title": "High CPU monitor",
      "description": "CPU utilization exceeded 90% for 10 minutes",
      "escalation_time": "2026-05-27T14:30:00+00:00",
      "markdown_summary": "## Root cause\nA retry storm from ...",
      "num_related_alerts": 1,
      "session_id": "3f9a1c2e-...",
      "source_integration": "DATADOG",
      "instance_group_variables": { "environment": "prod" }
    }
  ],
  "count": 1,
  "total": 114,
  "prev": null,
  "next": 2
}
```

| Field | Type | Description |
| - | - | - |
| `escalations[].alert_name` | `string \| null` | Alert name. |
| `escalations[].title` | `string` | Monitor name, or alert name if the monitor name is unavailable. |
| `escalations[].description` | `string` | Alert description. |
| `escalations[].escalation_time` | `string` | When the alert was escalated (ISO-8601). |
| `escalations[].markdown_summary` | `string` | Markdown summary of the investigation's findings. |
| `escalations[].num_related_alerts` | `integer` | Number of related alerts. |
| `escalations[].session_id` | `string` | Associated investigation session ID (see the [Sessions API](/api/sessions)). |
| `escalations[].source_integration` | `string \| null` | Source integration (e.g., `DATADOG`). |
| `escalations[].instance_group_variables` | `object` | Parsed instance group variables (e.g., `environment`, `kube_cluster_name`). |
| `count` | `integer` | Number of escalations in the current page. |
| `total` | `integer` | Total escalations across all pages. |
| `prev` | `integer \| null` | Previous page number, if any. |
| `next` | `integer \| null` | Next page number, if any. |

## Get statistics

`GET /v1/alerts/statistics`

Returns aggregate statistics about your organization's alerts over a time range: total volume,
investigated vs. noisy counts, noise-reduction percentage, and escalation response times.

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `start_time` | `string` | Inclusive lower bound on when the alert fired (timezone-aware ISO-8601). |
| `end_time` | `string` | Exclusive upper bound on when the alert fired (timezone-aware ISO-8601). |

### Example request

```bash theme={null}
curl "https://api.traversal.com/v1/alerts/statistics?start_time=2026-05-01T00:00:00Z&end_time=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer $TRAVERSAL_API_KEY"
```

### Example response

```json theme={null}
{
  "total_alerts": 1278,
  "num_investigated_alerts": 927,
  "num_noisy_alerts": 351,
  "noise_reduction": 27.46,
  "avg_response_time": 4733.99,
  "median_escalation_response_time": 212.36
}
```

| Field | Type | Description |
| - | - | - |
| `total_alerts` | `integer` | Total number of alerts in the time range. |
| `num_investigated_alerts` | `integer` | Alerts Traversal triggered for investigation. |
| `num_noisy_alerts` | `integer` | Alerts classified as noise. |
| `noise_reduction` | `number` | Noise reduction percentage (0–100). |
| `avg_response_time` | `number \| null` | Average escalation response time in minutes (`null` if none). |
| `median_escalation_response_time` | `number \| null` | Median escalation response time in minutes (`null` if none). |

## Errors

All errors use the standard [error envelope](/api/overview#error-format). In addition to the generic
status codes, these endpoints return `400` for an invalid time range or a `limit` above `100`, and
`403` if the Alert Intelligence API is not enabled for your organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.