Reading rounds

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
route_idstring · required
cycle_idstring · required
scheduled_atstring (date-time) · required
statusstring · required

one of planned, open, in_progress, completed, cancelled

opened_atstring · optional · nullable
completed_atstring · optional · nullable
cancelled_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "rea_2PpyaTHmkbFAofB8UXpw8xhESFx",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "status": "planned",
  "opened_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List route reading rounds

Logs

GET /reading-rounds

Returns a cursor-paginated page of reading rounds, each being one scheduled pass over a route for a cycle, with its status and the times it was opened, completed or cancelled. Use limit (default 20, maximum 100) and after to page. Requires business:reading-rounds:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

route_idstring · query · optional

Returns only rounds that walk this reading route ID.

cycle_idstring · query · optional

Returns only rounds that belong to this reading cycle ID.

statusstring · query · optional

Returns only rounds in this status: planned, open, in_progress, completed or cancelled; any other value returns 400.

one of planned, open, in_progress, completed, cancelled

Returns

200 Filtered reading rounds

Permissions business:reading-rounds:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/reading-rounds" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Filtered reading rounds

Schedule a reading round for a route and cycle

Logs

POST /reading-rounds

Plans a round of readings over a route for a cycle and returns it with status planned. route_id, cycle_id and scheduled_at are required (400 otherwise); the route must exist (404) and be active, or the call returns 409. Readers are then given meters through reading assignments while the round is planned or open.

Body application/json

route_idstring · required
cycle_idstring · required
scheduled_atstring (date-time) · required

Returns

201 Reading round created

Show attributes
idstring · required
tenant_idstring · required
route_idstring · required
cycle_idstring · required
scheduled_atstring (date-time) · required
statusstring · required

one of planned, open, in_progress, completed, cancelled

opened_atstring · optional · nullable
completed_atstring · optional · nullable
cancelled_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions business:reading-rounds:create · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/reading-rounds" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "rea_2PpyaTHmkbFAofB8UXpw8xhESFx",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "status": "planned",
  "opened_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get a reading round

Logs

GET /reading-rounds/{id}

Returns one reading round with its route, cycle, scheduled time, status and the opened, completed and cancelled timestamps. A round that does not exist in the tenant returns 404. Requires business:reading-rounds:read.

Parameters

idstring · path · required

ID of the reading round to return.

Returns

200 Reading round details

Show attributes
idstring · required
tenant_idstring · required
route_idstring · required
cycle_idstring · required
scheduled_atstring (date-time) · required
statusstring · required

one of planned, open, in_progress, completed, cancelled

opened_atstring · optional · nullable
completed_atstring · optional · nullable
cancelled_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions business:reading-rounds:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/reading-rounds/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "rea_2PpyaTHmkbFAofB8UXpw8xhESFx",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "status": "planned",
  "opened_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Advance or cancel a reading round

Logs

PATCH /reading-rounds/{id}/status

Moves a reading round to a new status and returns 204 with no body. Allowed moves are planned to open or cancelled, open to in_progress or cancelled, and in_progress to completed or cancelled; starting requires at least one assignment, and completing requires every assignment to be completed or cancelled. Any other move returns 409, an unknown status returns 400, and sending the current status again is a no-op. Requires business:reading-rounds:manage.

Parameters

idstring · path · required

ID of the reading round whose status to change.

Body application/json

statusstring · required

one of planned, open, in_progress, completed, cancelled

Returns

204 Reading round status changed

Permissions business:reading-rounds:manage · Roles: admin, field_supervisor, operations, owner

curl -X PATCH "$BUSINESS_API/reading-rounds/{id}/status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "planned"
}'
Response 204

Reading round status changed