Ask about auth, request shape, or code samples in your preferred language.

API Assistant

Every request to public SDK endpoints must include a valid API key header.

This endpoint does not require a request body.

Use this endpoint to retrieve readings for a meter across a validated time range.

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

x-api-key

meterId

Start of an absolute time range, e.g. `2026-01-14T00:00:00`. Send it together with `endTime`.

startTime

End of an absolute time range. Send it together with `startTime`.

endTime

Start of a daily window, as `HH:mm:ss`. Part of the relative range — send all four of these together.

startHour

End of a daily window, as `HH:mm:ss`. Part of the relative range.

endHour

How far back the relative range starts, as `<amount> <unit>`, e.g. `1 day`.

startOffset

How far back the relative range ends, as `<amount> <unit>`, e.g. `0 days`.

endOffset

Maximum number of rows to return. 1 to 500, and 500 by default.

limit

Cursor for the next page. Pass the `lastValue` string from the previous response back verbatim.

lastValue

Order rows by timestamp descending. Newest-first is already the default.

sortDesc

One object per reading timestamp. `null` — not an empty array — when the data source has no readings in the window you asked for.

data

One key per metric, named with the metric’s ID (e.g. `"33"`). `null` when that metric had no value at that timestamp. Get the ID-to-name mapping from `GET /data-sources/{id}` with `withSchema=true`.

data[].<metricId>

ID of the data source the row belongs to. A number here, even though the `meterId` you send in the query is a string.

data[].meter_id

Timestamp of the reading, UTC with microsecond precision. This is also the field pagination sorts on.

data[].event_date

Opaque cursor for the next page. Pass it back verbatim as `?lastValue=…`.

Returns one flat row per reading timestamp, newest first. Metric values are keys named after the metric ID, alongside `meter_id` and `event_date`. An opaque `lastValue` cursor sits next to `data` for fetching the next page.

Read meter data with validated time-range filters.

Get Readings


## `GET /reading`

Use this endpoint to retrieve readings for a meter across a validated time range.

## Authentication

```http
x-api-key: <your-api-key>
```

See [API Authentication](/developers/api-reference/api-authentication) for how to create a key.

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `meterId` | string | yes | Data source to read from. |
| `startTime` | string | no | Start of an absolute time range, e.g. `2026-01-14T00:00:00`. Send it together with `endTime`. |
| `endTime` | string | no | End of an absolute time range. Send it together with `startTime`. |
| `startHour` | string | no | Start of a daily window, as `HH:mm:ss`. Part of the relative range — send all four of these together. |
| `endHour` | string | no | End of a daily window, as `HH:mm:ss`. Part of the relative range. |
| `startOffset` | string | no | How far back the relative range starts, as `<amount> <unit>`, e.g. `1 day`. |
| `endOffset` | string | no | How far back the relative range ends, as `<amount> <unit>`, e.g. `0 days`. |
| `limit` | number | no | Maximum number of rows to return. 1 to 500, and 500 by default. |
| `lastValue` | string | no | Cursor for the next page. Pass the `lastValue` string from the previous response back verbatim. |
| `sortDesc` | boolean | no | Order rows by timestamp descending. Newest-first is already the default. |

## Response

`200 OK`

Returns one flat row per reading timestamp, newest first. Metric values are keys named after the metric ID, alongside `meter_id` and `event_date`. An opaque `lastValue` cursor sits next to `data` for fetching the next page.

```json
{
  "data": [
    {
      "33": 0.5,
      "34": 2.5,
      "meter_id": 17794,
      "event_date": "2026-01-14T12:44:20.000000Z"
    },
    {
      "33": 1,
      "34": 2,
      "meter_id": 17794,
      "event_date": "2026-01-14T12:28:36.000000Z"
    },
    {
      "33": null,
      "34": 1.5,
      "meter_id": 17794,
      "event_date": "2026-01-14T05:44:20.000000Z"
    }
  ],
  "lastValue": "eyJldmVudF9kYXRlIjoiMjAyNi0wMS0xNFQwNTo0NDoyMC4wMDAwMDBaIn0="
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | array (nullable) | One object per reading timestamp. `null` — not an empty array — when the data source has no readings in the window you asked for. |
| `data[].<metricId>` | number | string | null (nullable) | One key per metric, named with the metric’s ID (e.g. `"33"`). `null` when that metric had no value at that timestamp. Get the ID-to-name mapping from `GET /data-sources/{id}` with `withSchema=true`. |
| `data[].meter_id` | number | ID of the data source the row belongs to. A number here, even though the `meterId` you send in the query is a string. |
| `data[].event_date` | string | Timestamp of the reading, UTC with microsecond precision. This is also the field pagination sorts on. |
| `lastValue` | string | Opaque cursor for the next page. Pass it back verbatim as `?lastValue=…`. |

### Good to know

- Rows are flat and keyed by metric ID. There is no nested `readings` array.
- Do not treat the presence of `lastValue` as proof that more data exists — on this endpoint it comes back on every non-empty page, including the last one. Keep paging until `data` is `null`, or until you get fewer rows than the `limit` you asked for.
- Newest-first is the effective default ordering.
- `limit` accepts 1 to 500 and defaults to 500, so 500 rows is the largest page you can get.
- Metric filtering is not available on this endpoint — every metric on the data source comes back on every row.

## Paging through readings

Send a `limit`, then pass the `lastValue` from each response back as `?lastValue=…` to get the
next page. Treat the cursor as opaque — do not decode or build one yourself.

Stop when `data` comes back `null`, or when you receive fewer rows than the `limit` you asked
for. On this endpoint a `lastValue` is returned even on the final page, so its presence alone does
not mean more data exists.

## Mapping metric IDs to names

Row keys are metric IDs. Call
[Get Data Source List](/developers/api-reference/get-data-source-list) — every data source comes back
with its `meterSchema`, where `metrics[].metric.id` is the key you see here and
`metrics[].displayName` is its human-readable name.

## Errors

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

```json
{
  "message": "Internal server error.",
  "internalErrorCode": "02-001"
}
```

| Status | Meaning |
| --- | --- |
| `400` | The request failed validation — a missing required field, a field the schema does not allow, an unparseable body, a value out of range, or a malformed `lastValue`. |
| `401` | The API key resolved to a user context that is not allowed to read or write the record you asked for. |
| `403` | The `x-api-key` header is missing or is not a recognised key. API Gateway rejects the call before the endpoint runs, so the body is only `{"message":"Forbidden"}`. |
| `409` | The write conflicts with an existing record, or it references a record that does not exist. |
| `429` | The API key exceeded the rate limit or quota on its usage plan. Also returned by API Gateway rather than the endpoint. |
| `500` | Unexpected server error, or the database returned no result where one was required. |



## `POST /reading`

Use this endpoint to post readings in the primary SDK ingestion format, with values keyed by metric ID inside each reading.

## Authentication

```http
x-api-key: <your-api-key>
Content-Type: application/json
```

See [API Authentication](/developers/api-reference/api-authentication) for how to create a key.

## Request body

Send an array of meters, each with one or more timestamped readings keyed by metric ID.

```json
[
  {
    "meterId": "871",
    "readings": [
      {
        "timestamp": "2026-01-01T10:00:00Z",
        "values": {
          "501": 12.4,
          "502": 55
        }
      }
    ]
  }
]
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `meterId` | string | yes | Data source that will receive the readings. Must be a JSON string — a number is rejected. |
| `readings` | object[] | yes | One entry per timestamped reading for that data source. |
| `readings[].timestamp` | string | yes | When the reading was taken. Send `null` to use the server’s current time — but the key must be present either way. |
| `readings[].values` | object | yes | Metric IDs mapped to their values. Get the IDs from `GET /data-sources/{id}?withSchema=true`. |

## Response

`200 OK`

Returns the fixed string `"SUCCESS"`. There is no per-reading result and no generated ID, so treat the `200` itself as the signal — there is nothing in the body worth parsing.

```json
{
  "data": "SUCCESS"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | string | Always the literal `"SUCCESS"` on a 200. It never carries counts, IDs or per-row detail. |

### Good to know

- `SUCCESS` means the batch was accepted for ingestion, not that it is stored yet. Allow for a short lag before reading the same values back with `GET /reading`.
- The whole batch is accepted or rejected together. If the API key cannot write to any one data source in the payload, the request fails with `401` and nothing is written.
- Send `"timestamp": null` to have Zira stamp the current time. The key still has to be present — omitting it is a `400`.
- Reading objects take only `timestamp` and `values`; any other key inside a reading is rejected with `400`. Keys you add on the enclosing data-source object are ignored instead.
- Leave out metrics that Zira calculates. Any writable metric you omit from `values` is stored as `null` rather than left at its previous value.
- Do not add a query string to this request — it interferes with body validation and produces a misleading `400`.

## Errors

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

```json
{
  "message": "Internal server error.",
  "internalErrorCode": "02-001"
}
```

| Status | Meaning |
| --- | --- |
| `400` | The request failed validation — a missing required field, a field the schema does not allow, an unparseable body, a value out of range, or a malformed `lastValue`. |
| `401` | The API key resolved to a user context that is not allowed to read or write the record you asked for. |
| `403` | The `x-api-key` header is missing or is not a recognised key. API Gateway rejects the call before the endpoint runs, so the body is only `{"message":"Forbidden"}`. |
| `409` | The write conflicts with an existing record, or it references a record that does not exist. |
| `429` | The API key exceeded the rate limit or quota on its usage plan. Also returned by API Gateway rather than the endpoint. |
| `500` | Unexpected server error, or the database returned no result where one was required. |


Insert meter readings where values are sent as a metric map keyed by metric ID.

Add Readings


Use this guide when you need to implement or troubleshoot calculated fields and validation behavior for data sources.

This guide is based on the platform normalization and evaluation pipeline, including:

- `docs/context/architecture/expressions-formulas-validation.md`
- `docs/context/architecture/post-readings-normalization.md`

## Know the main schema fields

At schema level, a metric can define fields such as:

- `valueExpression`
- `formula`
- `reverseFormula`
- `reverseDenormalizeFormula`
- `validationFormula`

These values travel with the schema and are included in normalization and downstream evaluation.

## Understand the runtime flow

The high-level flow is:

1. A reading is posted through the public readings API.
2. The normalization path loads meter schema and metric metadata.
3. Values are normalized by data type and schema order.
4. Expression and formula metadata is attached to the meter configuration payload.
5. Validation rules run before insertion handoff.
6. Downstream evaluation uses the configured expressions and helper functions.

## Use validation rules carefully

Validation formulas support checks such as:

- `maxValue`
- `minValue`
- `minLength`
- `maxLength`
- `required`
- `allowedValues`
- `maxChangeFromPrevious`

These rules are enforced during normalization, not only at UI level.

## Plan for expression context

Evaluation context can include:

- current metric values
- previous and next metrics
- relative metrics
- helper functions such as metric lookup, date helpers, scaling helpers, and spreadsheet-like functions

If you depend on cross-metric or cross-device logic, confirm the required context is available before you write the formula.

## Watch the common failure cases

Common reasons expressions fail in practice:

- field references do not match the actual schema
- validation rules do not fit the metric data type
- a formula assumes a value exists before normalization has produced it
- reverse formulas drift from the UI conversion logic
- `maxChangeFromPrevious` behavior depends on previous-reading retrieval and time range assumptions

## Recommended implementation approach

1. Start with the simplest possible expression.
2. Validate the field type and schema order first.
3. Add validation only after the base calculation works.
4. Test against real readings, especially for previous-value checks.
5. Recheck behavior after any schema rename or metric reorder.

## Read next

- Open **Readings API** for the ingestion entry points.
- Open **Data Sources and Devices** for broader device-related setup context.


Understand how expressions, formulas, reverse formulas, and validation rules behave across schema configuration, normalization, and runtime evaluation.

https://api.zira.us/public/reading

Description