Reading requests

Base URL: $BUSINESS_API

List on-demand and scheduled remote reading requests

Logs

GET /reading-requests

Returns a cursor-paginated page of on-demand reading requests sent to remote reading integrations, with their status, due time, attempt count, failure reason and the reading they produced. Requests created by reading schedules carry the schedule_id. Use limit (default 20, maximum 100) and after to page. Requires business:reading-requests:read.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

meter_idstring · query · optional

Returns only requests for this meter ID.

source_idstring · query · optional

Returns only requests addressed to this integration ID (the remote reading source).

statusstring · query · optional

Returns only requests in this status: requested, assigned, acquired, failed or expired; any other value returns 400.

one of requested, assigned, acquired, failed, expired

Returns

200 Remote reading requests in the authenticated utility tenant

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

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

Remote reading requests in the authenticated utility tenant

Create reading request

Logs

POST /reading-requests

Request an on-demand reading from an active utility integration

Asks an active remote reading integration to fetch a reading from an active meter; the integration later leases the request and reports the reading or a failure. meter_id, source_id and idempotency_key (at most 160 characters) are required, and due_at defaults to 10 minutes from now and must fall within the next 30 days. Repeating a call with the same source_id and idempotency_key returns the existing request, but reusing the key for a different meter or due time returns 409, as does a meter that is not active. An integration that is not active returns 403.

Body application/json

meter_idstring · required
source_idstring · required
idempotency_keystring · required
due_atstring (date-time) · optional

Returns

201 Reading request 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.

source_idstring · required
schedule_idstring · optional
requested_bystring · required
idempotency_keystring · required
statusstring · required

one of requested, assigned, acquired, failed, expired

requested_atstring (date-time) · required
due_atstring (date-time) · required
leased_untilstring · optional · nullable
attempt_countinteger · required
reading_idstring · optional
failure_reasonstring · optional
completed_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

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

curl -X POST "$BUSINESS_API/reading-requests" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "idempotency_key": "idempotency key",
  "due_at": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "rea_2eWRvUW5nok7pACPzSSNhEA7Bqk",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
  "requested_by": "requested by",
  "idempotency_key": "idempotency key",
  "status": "requested",
  "requested_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "leased_until": "2026-11-19T09:30:00Z",
  "attempt_count": 1,
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "failure_reason": "failure reason",
  "completed_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}