Meters: Actions

Base URL: $BUSINESS_API

Installation history of one meter

Logs

GET /meters/{id}/installations

Returns every installation of this meter, past and current, with the connection, account, installation time, initial reading and seal number, using cursor pagination. Requires the business:meters:read permission.

Parameters

idstring · path · required

ID of the meter whose installation history is listed.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Installations, newest first

Show attributes
dataarray of MeterInstallation · required
Show child attributes
idstring · required
tenant_idstring · required
connection_idstring · required
connection_holder_namestring · optional

Display name of the customer who holds the referenced connection. Omitted when unknown.

meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · optional
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

installed_atstring (date-time) · required
initial_readingstring · required
removed_atstring · optional · nullable
final_readingstring · optional
exchange_reasonstring · optional
installed_bystring · required
security_seal_numberstring · optional
replaced_installation_idstring · optional
idempotency_keystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 403

Permissions business:meters:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/meters/{id}/installations" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "met_2yk9v6SNluyXngonlgs1hccPdGU",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
      "connection_holder_name": "Ana Matsinhe",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "installed_at": "2026-11-19T09:30:00Z",
      "initial_reading": "initial reading",
      "removed_at": "2026-11-19T09:30:00Z",
      "final_reading": "final reading",
      "exchange_reason": "exchange reason",
      "installed_by": "installed by",
      "security_seal_number": "SEC-2026-000142",
      "replaced_installation_id": "rep_2rLgATXYm9pMiLbYyNLwCPHAGTv",
      "idempotency_key": "idempotency key",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Get master meter balance

Logs

GET /meters/{id}/balance

Compute water balance for a master meter against its sub-meters

Sums the consumption recorded for the master meter and for each of its sub-meters over the period (litres are converted to cubic metres) and returns the unaccounted loss, the loss percentage and a negative_balance flag when the sub-meters add up to more than the master. Returns 400 when the meter is not a master meter or the period ends before it starts. Requires the business:meters:read permission.

Parameters

idstring · path · required

ID of a meter whose role is master.

fromstring (date-time) · query · optional

RFC 3339 start of the period, matched against the end of each consumption period; defaults to the first day of the current month in UTC.

tostring (date-time) · query · optional

RFC 3339 end of the period; defaults to the first day of next month in UTC and must not be before from.

Returns

200 Master meter water balance

Show attributes
master_meter_idstring · optional
serial_numberstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
master_consumption_m3number · optional
submeters_consumption_m3number · optional
unaccounted_loss_m3number · optional
loss_percentnumber · optional
negative_balanceboolean · optional
submeter_countinteger · optional
submetersarray of SubmeterBalanceEntry · optional
Show child attributes
meter_idstring · optional
serial_numberstring · optional
account_idstring · optional
consumption_m3number · optional

Permissions business:meters:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/meters/{id}/balance" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "master_meter_id": "mas_2Uq5JwONfeqHfCIDxsqZNqUJNOY",
  "serial_number": "SER-2026-000142",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "master_consumption_m3": 13.42,
  "submeters_consumption_m3": 13.42,
  "unaccounted_loss_m3": 1,
  "loss_percent": 1,
  "negative_balance": true,
  "submeter_count": 1,
  "submeters": [
    {
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "serial_number": "SER-2026-000142",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "consumption_m3": 13.42
    }
  ]
}

Change a meter's operational status

Logs

PATCH /meters/{id}/status

Sets the meter's status to active, inactive or retired and returns 204 with no body; setting the status it already has changes nothing. Retiring a meter records its removal time and marks the device as scrapped. Returns 400 for any other status and 404 when the meter does not exist. Requires the business:meters:manage permission.

Parameters

idstring · path · required

ID of the meter in the caller's tenant.

Body application/json

statusstring · required

one of active, inactive, retired

Returns

204 Meter status updated

Errors 400 · 403 · 404

Permissions business:meters:manage · Roles: admin, operations, owner

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

Meter status updated

List audit resets recorded for a meter

Logs

GET /meters/{id}/resets

Returns the resets recorded for the meter, each with the prior and new reading values, reason, reset time and the user who authorized it, using cursor pagination. Requires the business:meters:read permission.

Parameters

idstring · path · required

ID of the meter whose resets are listed.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Meter resets recorded for this meter

Show attributes
dataarray of MeterReset · required
Show child attributes
idstring · required
tenant_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

reset_atstring (date-time) · required
prior_reading_valuestring · required
reset_reading_valuestring · required
reasonstring · required
authorized_bystring · required
idempotency_keystring · required
created_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 403

Permissions business:meters:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/meters/{id}/resets" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "met_21FsuzPQGN5aoRn4qbXm4zhaCTz",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "reset_at": "2026-11-19T09:30:00Z",
      "prior_reading_value": "prior reading value",
      "reset_reading_value": "reset reading value",
      "reason": "Leitura confirmada no local.",
      "authorized_by": "authorized by",
      "idempotency_key": "idempotency key",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Record an authorized meter reset baseline

Logs

POST /meters/{id}/reset

Records a reset of the meter's register: reset_reading_value becomes the new baseline and prior_reading_value (defaulting to the last accepted reading at or before reset_at) is kept for audit; reset_at defaults to now and must fall between installation and now. reason and idempotency_key are required; repeating the key with identical values returns the existing reset, and with different values returns 409. Returns 409 when the meter is not active. Requires the business:meters:manage permission.

Parameters

idstring · path · required

ID of the active meter being reset.

Body application/json

reset_atstring (date-time) · optional
prior_reading_valuestring · optional
reset_reading_valuestring · required
reasonstring · required
idempotency_keystring · required

Returns

201 Meter reset recorded

Show attributes
idstring · required
tenant_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

reset_atstring (date-time) · required
prior_reading_valuestring · required
reset_reading_valuestring · required
reasonstring · required
authorized_bystring · required
idempotency_keystring · required
created_atstring (date-time) · required

Errors 400 · 403 · 404 · 409

Permissions business:meters:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/{id}/reset" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reset_at": "2026-11-19T09:30:00Z",
  "prior_reading_value": "prior reading value",
  "reset_reading_value": "reset reading value",
  "reason": "Leitura confirmada no local.",
  "idempotency_key": "idempotency key"
}'
Response 201
{
  "id": "met_21FsuzPQGN5aoRn4qbXm4zhaCTz",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "reset_at": "2026-11-19T09:30:00Z",
  "prior_reading_value": "prior reading value",
  "reset_reading_value": "reset reading value",
  "reason": "Leitura confirmada no local.",
  "authorized_by": "authorized by",
  "idempotency_key": "idempotency key",
  "created_at": "2026-11-19T09:30:00Z"
}

Get the metadata of a meter

Logs

GET /meters/{id}/metadata

Returns the key-value metadata stored on the meter, or an empty map when none is set. Returns 404 when the meter does not exist in the caller's tenant. Requires the business:metadata:read permission.

Parameters

idstring · path · required

ID of the meter in the caller's tenant, at most 120 characters.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/meters/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /meters/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the given keys into the meter's existing metadata and returns the full result; keys not sent are kept, and sending a key with an empty string removes it. Keys must be 1 to 40 characters with no square brackets or control characters, values at most 500 characters, and a meter can hold at most 50 keys; violations return 400 listing each invalid field. Requires the business:metadata:write permission.

Parameters

idstring · path · required

ID of the meter in the caller's tenant, at most 120 characters.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/meters/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

List meter commands

Logs

GET /meters/{id}/commands

Returns the commands queued for the meter with their status, type, assigned collector and timestamps, using cursor pagination. Requires the business:meter-commands:read permission.

Parameters

idstring · path · required

ID of the meter whose commands are listed.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Meter commands

Show attributes
dataarray of MeterCommand · required
Show child attributes
idstring · required
tenant_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

collector_idstring · required
typestring · required

one of read, inspect, synchronize, reset-alarm, disconnect, reconnect

statusstring · required

one of queued, leased, succeeded, failed, cancelled

requested_bystring · required
idempotency_keystring · required
reading_idstring · optional
failure_reasonstring · optional
attempt_countinteger · required
max_attemptsinteger · required
lease_expires_atstring (date-time) · optional
not_beforestring (date-time) · required
expires_atstring (date-time) · optional
completed_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 403

Permissions business:meter-commands:read · Roles: admin, operations, owner

curl -X GET "$BUSINESS_API/meters/{id}/commands" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "met_2bnQGDJiSNNWkZDKO3j04p3KOX7",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt",
      "type": "read",
      "status": "queued",
      "requested_by": "requested by",
      "idempotency_key": "idempotency key",
      "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
      "failure_reason": "failure reason",
      "attempt_count": 1,
      "max_attempts": 1,
      "lease_expires_at": "2026-11-19T09:30:00Z",
      "not_before": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "completed_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create meter command

Logs

POST /meters/{id}/commands

Queue a command against a meter. read and inspect need business:meter-commands:create, synchronize and reset-alarm need supervise, disconnect and reconnect need actuate and are audited.

Queues the command for the collector assigned to the meter and returns it with 201 in queued status; it expires after 24 hours and is tried at most 5 times. An idempotency_key repeated for the same meter and type returns the existing command, and for a different meter or type returns 409. Returns 409 with code METER_NO_COLLECTOR when no collector is assigned, 404 when the meter is not in the tenant, and 400 for an unknown type or parameters larger than 8 KB.

Parameters

idstring · path · required

ID of the meter in the caller's tenant that the command is sent to.

Body application/json

typestring · required

one of read, inspect, synchronize, reset-alarm, disconnect, reconnect

idempotency_keystring · optional
parametersobject · optional

Returns

201 Command queued

Show attributes
idstring · required
tenant_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

collector_idstring · required
typestring · required

one of read, inspect, synchronize, reset-alarm, disconnect, reconnect

statusstring · required

one of queued, leased, succeeded, failed, cancelled

requested_bystring · required
idempotency_keystring · required
reading_idstring · optional
failure_reasonstring · optional
attempt_countinteger · required
max_attemptsinteger · required
lease_expires_atstring (date-time) · optional
not_beforestring (date-time) · required
expires_atstring (date-time) · optional
completed_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404 · 409

Permissions business:meter-commands:create · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/{id}/commands" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "read",
  "idempotency_key": "idempotency key",
  "parameters": {}
}'
Response 201
{
  "id": "met_2bnQGDJiSNNWkZDKO3j04p3KOX7",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt",
  "type": "read",
  "status": "queued",
  "requested_by": "requested by",
  "idempotency_key": "idempotency key",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "failure_reason": "failure reason",
  "attempt_count": 1,
  "max_attempts": 1,
  "lease_expires_at": "2026-11-19T09:30:00Z",
  "not_before": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Report whether remote commands can reach a meter

Logs

GET /meters/{id}/commands/capability

A meter without an active collector assignment cannot receive commands; creating one then answers 409 with code METER_NO_COLLECTOR.

Parameters

idstring · path · required

ID of the meter to check; the response says whether a collector is assigned to it and which one.

Returns

200 Command capability

Show attributes
has_collectorboolean · required
collector_idstring · optional

Errors 403

Permissions business:meter-commands:read · Roles: admin, operations, owner

curl -X GET "$BUSINESS_API/meters/{id}/commands/capability" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "has_collector": true,
  "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt"
}

Get a meter command

Logs

GET /meters/{id}/commands/{command_id}

Returns one command with its type, status, parameters, assigned collector and timing. Returns 404 when the command does not exist in the tenant or belongs to a different meter than the one in the path. Requires the business:meter-commands:read permission.

Parameters

idstring · path · required

ID of the meter the command was sent to.

command_idstring · path · required

ID of the command; it must belong to the meter given in id.

Returns

200 Meter command

Show attributes
idstring · required
tenant_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

collector_idstring · required
typestring · required

one of read, inspect, synchronize, reset-alarm, disconnect, reconnect

statusstring · required

one of queued, leased, succeeded, failed, cancelled

requested_bystring · required
idempotency_keystring · required
reading_idstring · optional
failure_reasonstring · optional
attempt_countinteger · required
max_attemptsinteger · required
lease_expires_atstring (date-time) · optional
not_beforestring (date-time) · required
expires_atstring (date-time) · optional
completed_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 403 · 404

Permissions business:meter-commands:read · Roles: admin, operations, owner

curl -X GET "$BUSINESS_API/meters/{id}/commands/{command_id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "met_2bnQGDJiSNNWkZDKO3j04p3KOX7",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt",
  "type": "read",
  "status": "queued",
  "requested_by": "requested by",
  "idempotency_key": "idempotency key",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "failure_reason": "failure reason",
  "attempt_count": 1,
  "max_attempts": 1,
  "lease_expires_at": "2026-11-19T09:30:00Z",
  "not_before": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Move a meter that is not on a connection

Logs

POST /meters/{id}/device-status

Move a meter that is not on a connection: testing, back to a warehouse, or scrap

The meter module stays the owner of the meter; inventory moves its serial in the same transaction and refuses the change when the serial is not where the action claims. Installed meters leave their connection through an exchange.

Parameters

idstring · path · required

Meter ID (mtr_)

Body application/json

statusstring · required

one of in_warehouse, in_testing, scrapped

location_idstring · optional

Destination warehouse or van of a meter returned in_warehouse (the default warehouse when empty)

reasonstring · required

Returns

200 Meter with its new device status

Errors 400 · 401 · 403 · 404 · 409

Permissions business:meters:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/{id}/device-status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "in_warehouse",
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local."
}'
Response 200

Meter with its new device status