Alert Intelligence API

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.

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 to create an API key. For base URL, error envelope, and generic status codes, see the API overview.

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

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

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

{
  "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).
`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

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

{
  "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. 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.

Get Started

Architecture

Set up

Using Traversal

API

Security & Trust

Changelog

Alert Intelligence API

Required roles

Time-range filtering

List escalations

Query parameters

Example request

Example response

Get statistics

Query parameters

Example request

Example response

Errors

​Required roles

​Time-range filtering

​List escalations

​Query parameters

​Example request

​Example response

​Get statistics

​Query parameters

​Example request

​Example response

​Errors

Required roles

Time-range filtering

List escalations

Query parameters

Example request

Example response

Get statistics

Query parameters

Example request

Example response

Errors