---
title: "Get Escalations"
method: GET
path: "/analytics/escalations"
tags: ["analytics"]
---

# Get Escalations

`GET /analytics/escalations`

## Request

- Base URL: `https://api.verdun.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.verdun.ai/analytics/escalations`
- Auth: HTTP bearer

Reporting -> Escalations: one row per escalated alarm (Escalate - Voice
Down or Escalate - Dispatch, Site Summary's own definition) with its full
action timeline on one clock, and KPI medians over the FULL filtered set.

The window keys on the ESCALATION INSTANT (the operator close-out, else the
AI announcement), like Site Summary, so an alarm created before the window
start but escalated inside it appears; rows are ordered by when the alarm
landed. Tenant scoping is /analytics/incidents': a forged parent/site/camera
filter is 403, rows outside the caller's grants never appear. Operator names
are returned only to owner / monitoring manager; everyone else sees
"Operator". Customer-side logins also lose internal-only detail.

## Query parameters

- `hours` integer, nullable: Rolling window ending now (default 168 = 7 days). start/end win when both are given.
- `start` string, date-time, nullable
- `end` string, date-time, nullable
- `parent_id` string[], nullable
- `site_id` string[], nullable
- `camera_id` string[], nullable
- `kind` 'voice_down' | 'dispatch', nullable
- `escalated_by` 'operator' | 'agent', nullable
- `limit` integer

## Response `200`

Successful Response

- GetEscalationsResponse
  - `window` EscalationWindow, required
    - `start` string, date-time, required: Inclusive UTC start of the requested window.
    - `end` string, date-time, required: UTC end of the requested window.
  - `total` integer, required: Rows matching the filters, uncapped by `limit`.
  - `returned` integer, required: Rows in this response.
  - `limit` integer, required: The applied limit.
  - `kpi_truncated` boolean: True when the filtered set exceeded the server's candidate cap and the KPIs cover the newest rows only.
  - `kpis` EscalationKpis, required
    - `escalate_seconds` KpiMedian, required
      - `median` integer, nullable: Median seconds over the full filtered set (half-up).
      - `n` integer, required: Rows that contributed (timing not null).
    - `voice_down_seconds` KpiMedian, required
      - `median` integer, nullable: Median seconds over the full filtered set (half-up).
      - `n` integer, required: Rows that contributed (timing not null).
    - `dispatcher_answered_seconds` KpiMedian, required
      - `median` integer, nullable: Median seconds over the full filtered set (half-up).
      - `n` integer, required: Rows that contributed (timing not null).
    - `contact_reached_seconds` KpiMedian, required
      - `median` integer, nullable: Median seconds over the full filtered set (half-up).
      - `n` integer, required: Rows that contributed (timing not null).
    - `closed_seconds` KpiMedian, required
      - `median` integer, nullable: Median seconds over the full filtered set (half-up).
      - `n` integer, required: Rows that contributed (timing not null).
  - `rows` EscalationRow[], required: Escalation rows in newest-first order.
    - `event_id` string, uuid, required: The alarm.
    - `site` EscalationSite, required
      - `id` string, uuid, required: Site id.
      - `name` string, required: Site name.
      - `timezone` string, nullable: IANA zone the UI renders this row's clock in.
    - `parent` EscalationParent, required
      - `id` string, uuid, required: Client (parent) id.
      - `name` string, required: Client name.
    - `camera` EscalationCamera, required
      - `id` string, uuid, required: Camera id.
      - `label` string, required: Camera label (an identifier, never scrubbed).
    - `incident_type` string, nullable: AI incident class, when known.
    - `kind` 'voice_down' | 'dispatch', required: Escalate - Voice Down or Escalate - Dispatch.
    - `escalated_by` 'agent' | 'operator', required: Who owns the escalation (the operator's when both acted).
    - `agent_voice_down` boolean, required: The AI agent also played a deterrent on this alarm.
    - `operator` string, nullable: The escalating operator, projected like actor_name; null for agent-only rows.
    - `t0` string, date-time, required: When the alarm entered the operator queue (shared queue clock); event creation is the fallback when queue visibility is unknown.
    - `state` 'open' | 'closed' | 'expired', required: Open, closed out, or expired without a close-out.
    - `outcome` EscalationOutcome
      - `code` string, required: Close-out outcome word, or agent_cleared / closed / expired.
      - `tone` 'good' | 'warn' | 'bad' | 'neutral', required: Colour hint.
    - `timings` EscalationTimings, required
      - `escalate_seconds` integer, nullable: Alarm to the first escalating action.
      - `voice_down_seconds` integer, nullable: Alarm to the first voice down transmitted or played.
      - `dispatcher_answered_seconds` integer, nullable: Alarm to the dispatcher answering (derived instant).
      - `contact_reached_seconds` integer, nullable: Alarm to the first contact call answered or first SMS delivered.
      - `closed_seconds` integer, nullable: Alarm to close-out.
    - `poster_url` string, nullable: Blind presign of the alert snapshot; the image may 404.
    - `clip` EscalationClip, required
      - `available_hint` boolean, required: The alarm has a clip key and is inside the storage window (or retained). A hint, never a HEAD.
      - `retained` boolean, required: A starred copy exists.
    - `captures` EscalationCaptureSummary[], required: After-voice-down recordings for this alarm.
      - `id` string, uuid, required: Capture id; fetch playback from GET /events/{id}/captures.
      - `trigger_kind` string, required: Which action it follows: a voice-down kind (ai_announcement, operator_ai_announcement, live_talk, external_talkdown, clip_talkdown), or operator_alarm, which is the operator-raised alarm's OWN clip (30 s before it was raised to 15 s after), not an after-voice-down recording.
      - `status` string, required: pending, claimed, captured, unavailable or failed.
      - `reason` string, nullable: Why it is unavailable/failed.
      - `offset_seconds` integer, required: Seconds from the alarm to the start of the recording.
      - `captured_seconds` number, nullable: Footage recorded inside the window (null when not measured).
      - `start_offset_seconds` number, nullable: Where the footage begins inside the window.
      - `partial` boolean, nullable: True when less than the full window was recorded.
    - `steps` EscalationStep[], required: Timeline steps ordered by timestamp.
      - `kind` string, required: alarm, raised (an operator raised it from Live View), ai_assessment, opened, escalated, announcement, announcement_failed, ai_call_ended, live_talk, live_talk_end, external_talkdown, external_talkdown_end, owner_call, owner_sms, owner_email, contact_reply, dispatch_call, dispatch_connected, dispatch_ended, closed, expired.
      - `actor` 'system' | 'agent' | 'operator', required: Who acted: the system, the AI agent, or an operator.
      - `actor_name` string, nullable: Operator display name for ops-lead callers; the literal 'Operator' for everyone else; null for system/agent steps.
      - `at` string, date-time, required: Absolute UTC instant of the step.
      - `offset_seconds` integer, required: Seconds since the alarm landed in the queue (t0), never negative.
      - `since_previous_seconds` integer, nullable: Seconds since the previous step; null on the first.
      - `label` string, required: Short English label.
      - `detail` object, nullable: Structured facts for the step. Customer-side callers receive only an allow-listed subset of keys.
      - `result` EscalationResult
        - `code` string, required: Stable machine word (answered, delivered, no_answer, played, subject_left, ...).
        - `tone` 'good' | 'warn' | 'bad' | 'neutral', required: good | warn | bad | neutral - the UI colour, decided server-side.
      - `capture_id` string, uuid, nullable: The after-voice-down capture that follows this step (voice steps only).
      - `derived` boolean: True when the instant is derived, not recorded (the 'escalated' step is the first escalating action).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verdun/apis/verdun-api.md) - [All operations](https://skmtc.dev/verdun/apis/verdun-api/llms.txt) - [OpenAPI document](https://skmtc.dev/verdun/apis/verdun-api/revisions/00252d8227c1?raw)