---
title: "Get an escalation path"
method: GET
path: "/escalation-paths/{path}"
tags: ["Escalation paths"]
---

# Get an escalation path

`GET /escalation-paths/{path}`

## Request

- Base URL: `https://api.spectate.net/v1`
- URL: `https://api.spectate.net/v1/escalation-paths/{path}`
- Auth: HTTP bearer

Returns the path with its steps as a tree and the problems that keep it from delivering.

## Path parameters

- `path` string, uuid, required

## Response `200`

The escalation path.

- EscalationPath: An escalation path: what happens when an alert fires, step by step, until someone acknowledges it. Monitors, hosts, domains and alert sources use their own paths, their project's, or the team's default path.
  - `id` string, uuid, required: Escalation path ID
  - `name` string, required: Name
  - `description` string, nullable, required: What the path is for
  - `enabled` boolean, required: Whether alerts follow the path. Alerts of a disabled path don't escalate
  - `is_default` boolean, required: Whether this is the team's default path, for resources without paths of their own or of their project. One per team
  - `working_hours` WorkingHours, required: Weekly working hours, for branch conditions and "until working hours" waits.
    - `timezone` string, required: IANA time zone the hours are in
    - `days` integer[], required: ISO weekdays, 1 (Monday) to 7 (Sunday)
    - `start_time` string, required: When working hours begin, as `HH:MM`
    - `end_time` string, required: When they end, as `HH:MM`; before `start_time` runs past midnight
    - `description` string, required: The hours in words
  - `group_window_minutes` integer, nullable, required: Group alerts on this path within this many minutes, extended with each alert that joins; `null`: each alert escalates by itself
  - `group_by` 'all' | 'project' | 'resource' | 'label', required: What alerts on an escalation path must share to be grouped. | | |---| | `all` <br/> Everything on the path. | | `project` <br/> The same project. | | `resource` <br/> The same monitor, host, domain or alert source. | | `label` <br/> The same value of a label an alert source sent. |
  - `group_label` string, nullable, required: With `group_by` `label`: which label
  - `steps` EscalationStep[], required: The steps, in order; a `branch` continues in its `then` and `else` steps
    - `key` string, nullable, required: The step's key in the path, which a `repeat` names in `go_to`
    - `type` 'notify_channel' | 'create_incident' | 'notify_on_call' | 'notify_users' | 'repeat' | 'branch', required: What an escalation step does. | | |---| | `notify_channel` <br/> Send the alert to a channel. | | `create_incident` <br/> Declare an incident for the alert. | | `notify_on_call` <br/> Page people on a schedule: whoever is on call (default), whoever is on call next, or everyone on it; optionally in one rotation (layer). Each is paged by their own notification rules. | | `notify_users` <br/> Page chosen team members, or the whole team, by their own notification rules. | | `repeat` <br/> Go back to an earlier step, up to a number of times; ends the escalation after the last time. | | `branch` <br/> If/else: alerts meeting every condition continue on its `then` side, the rest on its `else` side. |
    - `delay_minutes` integer, nullable, required: Minutes to wait before the step runs (a branch or repeat: before it's decided); `null` when `delay_until` applies
    - `delay_until` 'working_hours_start' | 'working_hours_end', required: Instead of a fixed delay, an escalation step can wait for the path's working hours to begin (no wait during working hours) or to end (no wait outside them). | | |---| | `working_hours_start` <br/> Wait until working hours begin; no wait during working hours. | | `working_hours_end` <br/> Wait until working hours end; no wait outside them. |
    - `channel` ChannelReference, required: A channel something sends to.
      - `id` string, uuid, required: Channel ID
      - `name` string, required: Channel name
      - `type` 'email' | 'slack' | 'discord' | 'microsoft_teams' | 'telegram' | 'webhook' | 'pushover' | 'sms' | 'voice', required
      - `enabled` boolean, required: Whether it delivers; disabled channels are skipped
    - `schedule` OnCallScheduleReference, required: An on-call schedule something pages.
      - `id` string, uuid, required: On-call schedule ID
      - `name` string, required: Schedule name
    - `target` 'current' | 'next' | 'everyone', required: Who a `notify_on_call` step pages on its schedule (or on one rotation of it). | | |---| | `current` <br/> Whoever is on call when the step runs. | | `next` <br/> Whoever is on call after the current person: a fallback when the first one doesn't respond. | | `everyone` <br/> Everyone in the schedule's rotations, plus whoever covers by override. |
    - `rotation` OnCallScheduleReference, required: An on-call schedule something pages.
      - `id` string, uuid, required: On-call schedule ID
      - `name` string, required: Schedule name
    - `users` MemberReference[], nullable, required: `notify_users` steps: the members it pages (empty with `everyone`)
      - `id` string, uuid, required: Member (user) ID
      - `name` string, required: Name
      - `email` string, email, required: Email address
    - `everyone` boolean, nullable, required: `notify_users` steps: whether it pages the whole team
    - `urgency` 'high' | 'low', required: How urgently an escalation step pages people: picks which of their two lists of notification rules is used (high: e.g. app now, a phone call after 2 minutes; low: e.g. email only).
    - `repage_count` integer, nullable, required: Paging steps: times the same people are paged again while nobody acknowledges
    - `repage_interval_minutes` integer, nullable, required: Paging steps: minutes between those pages
    - `go_to` string, nullable, required: `repeat` steps: the `key` of the step it goes back to
    - `times` integer, nullable, required: `repeat` steps: how many times it goes back
    - `conditions` EscalationCondition[], nullable, required: `branch` steps: the conditions; all must hold for `then`
      - `field` 'severity' | 'working_hours' | 'source' | 'label' | 'alert_status', required: What an escalation branch can test about an alert (incident.io-style "if/else" branches). | | |---| | `severity` <br/> | | `working_hours` <br/> Whether the branch is reached inside the path's working hours. | | `source` <br/> The kind of check or integration that raised the alert (uptime, certificate, external…). | | `label` <br/> A label sent along by an alert source (`metadata.labels`), e.g. `env=production`. | | `alert_status` <br/> Whether the alert was acknowledged by the time the branch is checked: "still not acknowledged * after 30 minutes?". A branch on it also runs after an acknowledgement, which otherwise stops the escalation; resolved alerts never get this far. |
      - `operator` 'is_one_of' | 'is_not_one_of' | 'within' | 'outside' | 'exists' | 'not_exists', required: How an escalation branch condition tests its field. `severity` and `source` take `is_one_of` and `is_not_one_of`; `working_hours` takes `within` and `outside`; `label` takes all four list and presence operators. | | |---| | `is_one_of` <br/> The value is one of `values`. | | `is_not_one_of` <br/> The value is none of `values`. | | `within` <br/> Reached inside the path's working hours. | | `outside` <br/> Reached outside the path's working hours. | | `exists` <br/> The label is set. | | `not_exists` <br/> The label isn't set. |
      - `key` string, nullable, required: `label` conditions: the label name sent by the alert source
      - `values` string[], required: Values to match, for `is_one_of` and `is_not_one_of`: severities (`critical`, `high`, `medium`, `low`), sources (`uptime`, `performance`, `certificate`, `dns`, `domain`, `host_metric`, `status_page`, `external`, or `external:<tool>` such as `external:grafana`) or label values
      - `description` string, required: The condition in words
    - `then` EscalationStep[], nullable, required: `branch` steps: what happens when the conditions hold
    - `else` EscalationStep[], nullable, required: `branch` steps: what happens otherwise
  - `warnings` EscalationPathWarning[], required: Problems that keep the path from reaching someone; empty when it can deliver
    - `code` 'no_deliverable_steps' | 'disabled_channels' | 'missing_schedules', required: A problem that keeps an escalation path from reaching someone. | | |---| | `no_deliverable_steps` <br/> Every notify step targets a disabled channel or a deleted schedule: alerts reach nobody. | | `disabled_channels` <br/> Some channels are disabled; their steps are skipped. | | `missing_schedules` <br/> An on-call step's schedule was deleted; the step is skipped. |
    - `message` string, required: The problem in words
  - `created_at` string, date-time, required: When the path was created

## Other responses

- `401`: `UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.
- `403`: `FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.
- `404`: `RESOURCE_NOT_FOUND`: there is no such resource in this team.
- `429`: `RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.

---

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