# Evacuations and headcount

> Evacuation types, states and phases, the headcount by person and by muster point, ruled-out points and the list of who is missing.

Page: https://safeonuba.com/en/developers/concepts/evacuations · SafeOnuba API v1 (`api_version: "2026-09-24"`), in preview: the contract may change.

An **evacuation** (`muster` in the API) is the headcount of a plant when people have to get out: who has reached a valid muster point, who is asking for help and who is missing. It’s what matters most to get right in your control room, and that’s why its events go out ahead of almost everything else.

> **The API doesn’t start evacuations**
>
> In v1 an evacuation always starts in the SafeOnuba dashboard: the system can propose it, but a person decides. Your control room receives it as soon as it starts (`muster.started`) and follows it until it ends.

## Type, status and phase

| kind | What it means |
| --- | --- |
| `general` | General evacuation. |
| `tsunami` | For a tsunami. It can carry `deadline`, the time limit. |
| `earthquake` | For an earthquake. |

The type can change during the evacuation (`muster.kind_changed`), and with it the muster points that are valid.

| status | What it means |
| --- | --- |
| `active` | Under way. |
| `completed` | Finished. |
| `cancelled` | Cancelled. |

| phase | What it means |
| --- | --- |
| `evacuating` | People are being evacuated. |
| `inspecting` | The headcount is complete and the control room is checking the plant. The watches say “don’t go back until further notice”. |

Other useful fields:

- `reason`: the reason, as text.
- `origin`: where the emergency comes from (coordinates, radius and zone). `null` in an evacuation without an origin, such as a general drill.
- `deadline`: in a tsunami, the time limit and where it comes from: `official` (an official warning) or `plan_estimate` (the ceiling in the zone’s plan). It is never a physical calculation.

## The headcount

`GET /v1/musters/{id}` returns the evacuation with its headcount in `totals`, calculated on the server with the same rule as the dashboard and the close-out: a precise position inside a valid point, or a declared arrival at one.

Each person is in one of these states:

| State | What it means |
| --- | --- |
| `safe` | Safe at a valid muster point. |
| `help` | Asking for help: trapped (`trapped`), injured (`injured`) or helping someone else (`helping`). |
| `wrong_point` | At a muster point that isn’t valid for this type of evacuation, or that the control room has ruled out. |
| `pending` | Hasn’t arrived yet. |
| `no_signal` | Their watch isn’t communicating. |
| `not_worn` | They aren’t wearing the watch. |

`totals` carries `expected` (how many people are expected) and the number of people in each state.

> **A closed evacuation keeps less**
>
> On closing, only the arrivals and the total are recorded. In a finished evacuation, the rest of the figures in `totals` and the `count` of each point come back `null`.

## Muster points

`assembly_points` lists the destinations for the evacuation type, ruled-out ones included, with how many people are safe at each (`count`).

The control room can **rule out** a point during the evacuation, for example because it falls inside the emergency’s radius or downwind, and can also reinstate it. A ruled-out point has `status: "excluded"` and an `excluded` object with:

- `reason`: why;
- `recommended`: whether the system had recommended it (by radius or by wind). Whoever rules it out is always a person;
- `at` and `by`: when and who.

Each change of destinations raises `targets_revision` and emits `muster.targets_changed`. Anyone who was at a ruled-out point moves to `wrong_point`.

## Who is missing

`GET /v1/musters/{id}/missing` returns the people who aren’t safe, ordered by urgency: first whoever is asking for help or needs rescue, then whoever is at a point that isn’t valid, without signal, without the watch on and still on their way out.

- `needs_rescue`: has an open SOS or fall and hasn’t arrived. They can’t get out on their own.
- `help_reason`: `trapped`, `injured` or `helping`.
- `assembly_point`: the point where they are or said they were, with `valid: false` if it isn’t valid.
- `location`: the last position, only with the `positions:read` scope and if the plant’s privacy level allows it to be seen. Otherwise, `location_withheld: true`.

## Evacuation events

| Event | When |
| --- | --- |
| `muster.started` | The evacuation starts. |
| `muster.kind_changed` | The type changes. |
| `muster.phase_changed` | The phase changes (`evacuating`, `inspecting`). |
| `muster.targets_changed` | The control room has ruled out or reinstated a muster point. |
| `muster.updated` | The headcount has changed. It is checked every 5 seconds and only emitted when it changes. |
| `muster.worker_missing` | Someone is missing. |
| `muster.ended` | It ends. |

A person who asks for help during the evacuation also generates an `evacuation_help` alert (`alert.created`), which carries the `muster_id` in its details.

Every event carries the complete evacuation in `data.muster`, so your control room can redraw the banner with the latest one that arrives. Since delivery order isn’t guaranteed, keep the most recent by `created_at` (see [Webhooks](https://safeonuba.com/en/developers/webhooks#order)).

## Testing it without evacuating anyone

The sandbox has a scenario that runs through an entire evacuation in 3 minutes: arrivals, a ruled-out point, a request for help and the close. See [Sandbox](https://safeonuba.com/en/developers/sandbox#a-complete-evacuation).