---
title: "List escalations"
method: GET
path: "/orgs/v1/{org_id}/escalations"
tags: ["Escalations"]
---

# List escalations

`GET /orgs/v1/{org_id}/escalations`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/orgs/v1/{org_id}/escalations`
- Auth: none declared

Org members see every escalation; a grant key or grant-only principal sees ONLY what it raised (the response's `scope` says which). Auth: SIWX wallet, control-plane session, or a run402_agent_key grant key. A project service_key is REJECTED — an escalation is agent judgement and needs a principal to attribute. Deny is 403, never 404. NEVER lifecycle-gated: an org in grace is exactly when an agent may most need a human. Paged newest-first: a capped page reports has_more and hands back next_cursor, so the remainder is never silently dropped.

## Path parameters

- `org_id` string, uuid, required

## Query parameters

- `status` 'open' | 'acknowledged' | 'resolved'
- `limit` integer
- `cursor` string

## Response `200`

escalations[] + scope

- AgentEscalationList
  - `escalations` AgentEscalation[]
    - `escalation_id` string, uuid
    - `org_id` string, uuid
    - `project_id` string, nullable: Soft reference — the escalation outlives the project's deletion.
    - `raised_by` object
      - `kind` 'principal' | 'rule': event-attention-rules: `rule` when a routing rule with channel escalation raised it — then principal_id is null and rule_id / rule_owner_email name the rule and who set it (rule_id is null once that rule is deleted).
      - `principal_id` string, uuid, nullable
      - `rule_id` string, uuid, nullable
      - `rule_owner_email` string, nullable
      - `grant_key_id` string, uuid, nullable
      - `presence_name` string, nullable
    - `severity` 'normal' | 'high'
    - `reason` string: The agent's argument, verbatim. Rendered as DATA everywhere it is shown. For a rule raise, the platform's composed account of the event or window: what happened, where, the bounded facts, and who set the rule.
    - `attached_count` integer: event-attention-rules: further matches of the raising rule that joined this escalation while it was open or acknowledged, instead of paging again. Always 0 for an agent raise.
    - `last_attached_at` string, date-time, nullable
    - `details` object: Structured sidecar. Readable here; never rendered into a page.
    - `status` 'open' | 'acknowledged' | 'resolved'
    - `level` integer: Which contact level is currently paged.
    - `raised_at` string, date-time
    - `deadline_at` string, date-time: When an unacknowledged escalation climbs to the next level.
    - `acknowledged` object, nullable
      - `at` string, date-time
      - `by_email` string, nullable
      - `channel` 'token' | 'authenticated'
    - `resolved` object, nullable
      - `at` string, date-time
      - `by_email` string, nullable
      - `note` string, nullable
    - `climbs` object[]: Append-only deadman history.
      - `from_level` integer
      - `to_level` integer
      - `at` string, date-time
      - `reason` 'deadline_lapsed'
    - `repage_count` integer: Top-level re-pages so far. At the bound the row rests OPEN — never auto-resolved.
    - `delivery_attempts` object[]: Only when include=delivery. What ACTUALLY happened on the wire, read from the audit log rather than assumed.
      - `email` string
      - `channel` string
      - `status` string
      - `error` string, nullable
      - `at` string, date-time
  - `scope` 'organization' | 'own': 'own' when the caller is a grant key or grant-only principal — it sees only what it raised.
  - `has_more` boolean
  - `next_cursor` string, nullable: Keyset continuation over (raised_at DESC, id). Null on the last page.

## Other responses

- `400`: Invalid input (missing/over-cap reason, malformed email, bad level or status).
- `401`: Missing or invalid auth.
- `403`: Not authorized (never a 404 existence oracle); also rate/open-bound denials (QUOTA_EXCEEDED with used/limit) and step-up required.

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)