Reading schedules

Base URL: $BUSINESS_API

List remote meter acquisition schedules

Logs

GET /reading-schedules

Returns a cursor-paginated page of recurring remote reading schedules, each with its meter, integration, interval, next run time and last request time. Use limit (default 20, maximum 100) and after to page. Requires business:reading-schedules: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 schedules for this meter ID.

source_idstring · query · optional

Returns only schedules that use this integration ID as the remote reading source.

statusstring · query · optional

Returns only schedules in this status, active or paused; any other value returns 400.

one of active, paused

Returns

200 Utility reading schedules

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

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

Utility reading schedules

Schedule recurring remote readings

Logs

POST /reading-schedules

Creates an active schedule that turns into a remote reading request for the meter every interval_seconds (between 60 and 31,536,000). meter_id and source_id are required; next_run_at defaults to now plus one interval and must fall within the next 365 days. The meter must be active (409 otherwise) and the integration must exist and be active (404 or 403). Schedules only produce requests when they are materialized.

Body application/json

meter_idstring · required
source_idstring · required
interval_secondsinteger · required
next_run_atstring (date-time) · optional

Returns

201 Reading schedule created

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
interval_secondsinteger · required
next_run_atstring (date-time) · required
statusstring · required

one of active, paused

last_requested_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

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

curl -X POST "$BUSINESS_API/reading-schedules" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "interval_seconds": 60,
  "next_run_at": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "rea_2WybNoeX7iixvo8x1GYvNoKH54S",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "interval_seconds": 60,
  "next_run_at": "2026-11-19T09:30:00Z",
  "status": "active",
  "last_requested_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Pause or resume a remote reading schedule

Logs

PATCH /reading-schedules/{id}/status

Pauses or resumes a reading schedule and returns 204 with no body. The status must be active or paused (400 otherwise), and an unknown schedule returns 404. A paused schedule is ignored when due schedules are materialized. Requires business:reading-schedules:manage.

Parameters

idstring · path · required

ID of the reading schedule to pause or resume.

Body application/json

statusstring · required

one of active, paused

Returns

204 Schedule status changed

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

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

Schedule status changed

Turn due schedules into idempotent reading requests

Logs

POST /reading-schedules/materialize

Turns every active schedule whose next run time has passed into a reading request due in 10 minutes, advances each schedule by one interval, and returns 201 with the requests in data. The body's limit (1 to 100, required) caps how many due schedules are processed, oldest first. Schedules whose integration is no longer active are skipped, and each schedule run has a fixed idempotency key, so calling again does not duplicate a request already created. Requires business:reading-schedules:run.

Body application/json

limitinteger · required

Returns

201 Due scheduled requests created

Permissions business:reading-schedules:run · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/reading-schedules/materialize" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 25
}'
Response 201

Due scheduled requests created