# Get zone device counts

Canonical page: https://docs.ovok.com/slim-apis/zones/get-zone-device-counts

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/zones/device-counts` |

[Authentication](/authentication) · [Access policies](/access-policies)

Returns device counts per zone for your project, with project-wide totals. A zone is a FHIR `Organization`.

**Auth:** Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant `Organization:search`, `Organization:read`, `Device:search` and `Device:read` (admins and super admins skip this check).
**Scope:** The caller's project (from the token).

## Request [#request]

### Query parameters [#query-parameters]

Each boolean is `true` only for the exact value `true`. Any other value is `false`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `all` | `boolean` | No | `true` counts every device in each zone, assigned or not, and ignores `effectiveSleepStatus`. Default `false`. |
| `effectiveSleepStatus` | `"disconnected"` \| `"connected"` \| `"awake"` \| `"away"` \| `"asleep"` | No | Count only devices in this state. A device that is not active counts as `disconnected`. |
| `includeUnassigned` | `boolean` | No | Also count devices with no resident and add a bucket for devices in no zone. Default `false`. |
| `includeEmpty` | `boolean` | No | Keep project zones that have no matching devices, with zero counts. Default `false`. |

## Behaviour [#behaviour]

- By default, `deviceCount` matches the rows `GET /v1/slim/device/live` returns for each zone: devices assigned to a resident.
- `all=true` counts every device in each zone, assigned or not, and ignores `effectiveSleepStatus`.
- `effectiveSleepStatus` (`disconnected`, `connected`, `awake`, `away`, `asleep`) counts only devices in that state. A device that is not active counts as `disconnected`.
- `includeUnassigned=true` also counts devices with no resident (unless `all=true` already does) and adds a bucket, with `organization` unset, for devices in no zone.
- `includeEmpty=true` keeps project zones that have no matching devices, with zero counts.
- For each zone, `assignedResidentDeviceCount` counts devices with a resident, and `activeDeviceCount` / `inactiveDeviceCount` split devices by whether they are currently active.
- Zones are sorted by `deviceCount`, highest first. `total` is the number of entries; the `total…Count` fields sum the per-zone counts.
- The route answers 503 when the device list cannot be built and no earlier complete list exists. Retry shortly.

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/zones/device-counts?includeEmpty=true&includeUnassigned=true' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Zone device counts retrieved successfully.

```json
{
  "total": 2,
  "totalDeviceCount": 18,
  "totalAssignedResidentDeviceCount": 15,
  "totalActiveDeviceCount": 14,
  "totalInactiveDeviceCount": 4,
  "resources": [
    {
      "organization": {
        "resourceType": "Organization",
        "id": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
        "name": "Zone A",
        "meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-10-09T08:00:00.000Z" }
      },
      "deviceCount": 15,
      "assignedResidentDeviceCount": 15,
      "activeDeviceCount": 12,
      "inactiveDeviceCount": 3
    },
    {
      "deviceCount": 3,
      "assignedResidentDeviceCount": 0,
      "activeDeviceCount": 2,
      "inactiveDeviceCount": 1
    }
  ]
}
```

The second entry is the bucket of devices in no zone. It appears with `includeUnassigned=true` and has no `organization`.

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of entries in `resources`. |
| `totalDeviceCount` | `integer` | Sum of `deviceCount` over all entries. |
| `totalAssignedResidentDeviceCount` | `integer` | Sum of `assignedResidentDeviceCount` over all entries. |
| `totalActiveDeviceCount` | `integer` | Sum of `activeDeviceCount` over all entries. |
| `totalInactiveDeviceCount` | `integer` | Sum of `inactiveDeviceCount` over all entries. |
| `resources` | `object[]` | One entry per zone, highest `deviceCount` first. |
| `resources[].organization` | `object` | The zone. Left out for the bucket of devices in no zone. |
| `resources[].organization.resourceType` | `"Organization"` | Always `Organization`. |
| `resources[].organization.id` | `string (uuid)` | Zone id. |
| `resources[].organization.name` | `string` | Zone name. |
| `resources[].organization.description` | `string` | Narrative text of the zone. Left out when there is none. |
| `resources[].organization.meta` | `object` | Left out when not available. |
| `resources[].organization.meta.project` | `string (uuid)` | Project that holds the zone. |
| `resources[].organization.meta.lastUpdated` | `string (ISO 8601 date-time)` | When the zone last changed. |
| `resources[].deviceCount` | `integer` | Devices counted in this entry. |
| `resources[].assignedResidentDeviceCount` | `integer` | Counted devices that have a resident. |
| `resources[].activeDeviceCount` | `integer` | Counted devices that are currently active. |
| `resources[].inactiveDeviceCount` | `integer` | Counted devices that are not active. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, you lack `Organization:search`, `Organization:read`, `Device:search` or `Device:read`, your session has no project, or you cannot access the project. |
| [`422`](/errors/validation-failed) | A query parameter fails validation. |
| [`503`](/errors/service-unavailable) | The device list cannot be built and no earlier complete list exists. Retry shortly. |
