Usage Readings
Cumulative monotonic asset usage readings with corrections and bulk capture.
Usage Readings API
Usage readings are cumulative meter values captured against a barcoded asset per usage metric (for example running hours or mileage). They feed usage-based equipment_test due computation. Readings are monotonic — a non-correction reading must be at least the latest value for the same asset and metric — and are captured as decimal strings.
Readings are nested under their asset. A bulk endpoint records many readings across assets in a single transaction.
Endpoints
| Method | URL | Description |
|---|---|---|
| GET | /api/v1/assets/{asset}/usage_readings |
List an asset's readings (newest first) |
| POST | /api/v1/assets/{asset}/usage_readings |
Record a reading |
| POST | /api/v1/usage_readings/bulk |
Record multiple readings in one transaction |
Authentication
Requires usage-readings:read (GET) or usage-readings:write (POST) with usage-readings.view and usage-readings.create permissions. Access is warehouse-scoped through UsageReadingPolicy.
Record a reading
POST /api/v1/assets/{asset}/usage_readings
| Field | Type | Required | Description |
|---|---|---|---|
metric_id |
int | Yes | list entry from the Usage Metric list |
reading |
decimal | Yes | Cumulative meter value |
recorded_at |
datetime | No | When the reading was taken |
is_correction |
bool | No | Marks an append-only correction that may lower the baseline |
A regression is rejected with 422, naming the current value (for example "The reading cannot be below the current reading of 250.50."). A correction row (is_correction=true) may be lower and becomes the new baseline once recorded — the latest reading by timestamp wins, not the highest value.
Bulk capture
POST /api/v1/usage_readings/bulk
Records an array of readings in one synchronous transaction and returns 201 with the created rows. Validation errors are keyed by row index.
Response shape
UsageReadingData emits readings as decimal strings. Collection key: usage_readings; singular: usage_reading.
When a usage-scheduled equipment_test metric has no readings for an asset, usage-based due cannot be computed; due computation degrades to time-only and surfaces an awaiting first reading flag.
Webhooks
Usage readings are high-volume and are recorded to the audit trail only (usage_reading.recorded); no webhook is dispatched.