> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Groups and zones

> Group devices for dispatch, resolve network zones from addresses and forecast capacity.

A group is a named set of devices that you dispatch together, and whose capacity you read as one. A zone is a network area that Flatpeak resolves to devices, so you never handle addresses.

## Groups

[Create a group](/docs/fleet-api/reference/groups/create.md) with exactly one of:

| Membership | How it works |
| :- | :- |
| `device_ids` | An explicit list, which changes only when you change it |
| `filter` | A rule, which Flatpeak re-evaluates as devices enroll, move or change |

```json Request body theme={"system"}
{
  "name": "Bristol batteries",
  "filter": {
    "device_types": ["BATTERY_STORAGE"],
    "zone_id": "zon_9b3c5d7e1f2a4b6c8d0e2f4a"
  }
}
```

A filter combines `device_types`, `program_id`, `zone_id` and a response-time range. The range matches the device's median `response_time.total_seconds`, and a device with no measured response time is excluded when a bound is set.

To dispatch a group, create a [VPP event](/docs/fleet-api/guides/dispatch/vpp-events.md) with its `group_id`. The event takes the members the group has at that moment. The group object carries `device_count` but not the device list: [list all group devices](/docs/fleet-api/reference/groups/list-devices.md) returns the current members' IDs, a page at a time, with the total in `count`. Plans, state and telemetry stay per device.

## Zones

[Create a zone](/docs/fleet-api/reference/zones/create.md) with a `definition`. It always names a `country_code`, and narrows the country with at most one of these:

| Field | The zone covers |
| :- | :- |
| None | The whole country |
| `states` | States or provinces, by their short code: `CA` for California, `NSW` for New South Wales. Available where addresses carry state codes: Australia, Canada and the US |
| `postal_codes` | Postal codes or prefixes in that country |
| `multipolygon` | A GeoJSON area |

```json Request body theme={"system"}
{
  "name": "California batteries",
  "definition": {
    "country_code": "US",
    "states": ["CA"]
  }
}
```

The country is required because a postal code or a state has no meaning without it: `2000` is central Sydney and also Antwerp.

Postal codes match as full codes or prefixes: `BS1` covers every postcode under it. Precision depends on the country:

| Country | Postal codes |
| :- | :- |
| UK, Netherlands (PC6) | Fine enough for network zones |
| Australia | Whole suburbs |
| France | Commune-sized. Use a `multipolygon` |
| US | Large routing areas. Use a `multipolygon`: one zone per service territory or constraint area, even when the area is disjoint |

Flatpeak resolves membership against enrollment addresses and re-evaluates it continuously, and you receive only device IDs. Resolving a new zone, or one whose `definition` you changed, can take time: create and update return `device_count` as `null`, and the count appears once membership is resolved. `zone.membership.update` fires as devices join or leave. [Update a zone](/docs/fleet-api/reference/zones/update.md) to rename it or replace its area; groups and programs that reference the zone follow.

[List all zone devices](/docs/fleet-api/reference/zones/list-devices.md) returns the IDs of the devices in the zone, a page at a time, with the total in `count`.

A zone is not dispatchable itself: create a group that filters on `zone_id` and dispatch the group. Use the same `zone_id` in a [program's](/docs/fleet-api/guides/programs.md) eligibility to enroll only inside an area.

## Capacity

The [capacity forecast](/docs/fleet-api/reference/groups/retrieve-capacity.md) returns the power and energy a group can dispatch over a future window. Pass `start_time`, `end_time` (90 days at most) and a `direction`.

Headroom comes from each member's demand forecast, state of charge, limits, backup reserve, export rule, charge-from-grid setting and consents, and Flatpeak derates it by the device's fulfillment history. `confidence` runs from 0 to 1 and drops further into the future and where telemetry has gaps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.