> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenaza.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Meter Readings for Consumer and Producer Contracts

> Fetch individual timestamped meter readings for consumer and producer contracts, with filtering by date range, device, and reading quality.

## Overview

Meter readings represent **individual timestamped measurements** from physical meters attached to consumer or producer contracts. Each reading captures an energy value in Wh along with metadata such as the measurement reason, data quality classification, OBIS number, and cancellation status.

Readings are retrieved per contract and support rich filtering so you can query specific time windows, devices, or modification events.

**Base URL:** `https://api.lumenaza.de/` · **Test URL:** `https://api.test.lumenaza.de/`

<Note>
  A meter reading is uniquely identified by the combination of its **`timestamp`**,
  **`obis_number`**, and **`device_identification`**. Avoid treating any single
  field alone as a unique key.
</Note>

***

## Consumer Meter Readings

### GET /v3/consumers/\{userID}/contracts/\{contractID}/meter\_readings/

Returns a paginated list of meter readings for a specific consumer contract.

### Path Parameters

| Parameter | Type | Description |
| - | - | - |
| `userID` | string | The unique ID of the consumer user. |
| `contractID` | string | The unique ID of the consumer contract. |

### Query Filters

All filter parameters are optional. Date/time filters accept ISO 8601 datetime strings.

| Parameter | Description |
| - | - |
| `created` | Exact match on the record creation datetime. |
| `created__gte` | Records created on or after this datetime. |
| `created__lte` | Records created on or before this datetime. |
| `modified` | Exact match on the last modification datetime. |
| `modified__gte` | Records modified on or after this datetime. |
| `modified__lte` | Records modified on or before this datetime. |
| `timestamp` | Exact match on the reading's measurement timestamp. |
| `timestamp__gte` | Readings measured on or after this datetime. |
| `timestamp__lte` | Readings measured on or before this datetime. |
| `device_identification` | Filter to a specific meter device by its identification string. |

### Response Fields

Each reading in the `results` array contains:

| Field | Type | Description |
| - | - | - |
| `device_identification` | string | Identifier of the meter device that produced this reading. |
| `timestamp` | string | ISO 8601 datetime when the measurement was taken. |
| `reason` | string | Reason for this reading (e.g., periodic, contract start/end). |
| `quality` | string | Data quality classification. See [Quality Values](#quality-values) below. |
| `value` | integer | Energy reading value in Wh. |
| `obis_number` | string | OBIS code identifying the measured quantity (e.g., `1-0:1.8.0`). |
| `is_cancelled` | boolean | Whether the meter operator has cancelled this reading. See note below. |
| `created` | string | ISO 8601 datetime when this record was first created in the system. |
| `modified` | string | ISO 8601 datetime when this record was last modified. |

### Cancellation

When `is_cancelled` is `true`, the meter operator has marked this reading as invalid. **Readings can only be modified when they are in a cancelled state.** Non-cancelled readings are considered finalized and locked.

### Quality Values

The `quality` field uses the following German-language classifications:

| Value | Meaning |
| - | - |
| `Abgelesener Wert` | Directly read value (highest confidence). |
| `Ersatzwert - geschätzt` | Estimated substitute value. |
| `Vorschlagswert` | Suggested/proposed value. |
| `Nicht verwendbarer Wert` | Non-usable value (rejected reading). |
| `Prognosewert` | Forecast/projected value. |
| `Energiemenge summiert` | Aggregated energy total. |

***

### Example: Filter by Timestamp Range

```bash theme={null}
curl -X GET "https://api.lumenaza.de/v3/consumers/USR-4821/contracts/CON-9934/meter_readings/?timestamp__gte=2024-03-01T00:00:00Z&timestamp__lte=2024-03-31T23:59:59Z" \
  -H "Authorization: Bearer <token>"
```

### Example Response

```json theme={null}
{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "device_identification": "1ESY1160052874",
      "timestamp": "2024-03-01T00:00:00Z",
      "reason": "Turnusablesung",
      "quality": "Abgelesener Wert",
      "value": 10482300,
      "obis_number": "1-0:1.8.0",
      "is_cancelled": false,
      "created": "2024-03-04T08:12:45Z",
      "modified": "2024-03-04T08:12:45Z"
    },
    {
      "device_identification": "1ESY1160052874",
      "timestamp": "2024-03-15T00:00:00Z",
      "reason": "Stichtagsablesung",
      "quality": "Ersatzwert - geschätzt",
      "value": 10619700,
      "obis_number": "1-0:1.8.0",
      "is_cancelled": false,
      "created": "2024-03-17T10:05:30Z",
      "modified": "2024-03-18T14:22:10Z"
    },
    {
      "device_identification": "1ESY1160052874",
      "timestamp": "2024-03-31T23:59:59Z",
      "reason": "Turnusablesung",
      "quality": "Abgelesener Wert",
      "value": 10784500,
      "obis_number": "1-0:1.8.0",
      "is_cancelled": true,
      "created": "2024-04-02T07:48:00Z",
      "modified": "2024-04-03T09:15:00Z"
    }
  ]
}
```

***

## Producer Meter Readings

### GET /v3/producers/\{userID}/contracts/\{contractID}/meter\_readings/

Returns a paginated list of meter readings for a specific producer contract. The response structure and all filter parameters are **identical** to the consumer endpoint.

### Path Parameters

| Parameter | Type | Description |
| - | - | - |
| `userID` | string | The unique ID of the producer user. |
| `contractID` | string | The unique ID of the producer contract. |

### Supported Filters

All filters available on the consumer endpoint apply here as well. The `device_identification` filter is particularly useful for producers with multiple meters or generation units on a single contract.

### Example Request

```bash theme={null}
curl -X GET "https://api.lumenaza.de/v3/producers/USR-7703/contracts/CON-1105/meter_readings/?device_identification=1ESY1160099321" \
  -H "Authorization: Bearer <token>"
```

The response follows the same paginated structure:

```json theme={null}
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "device_identification": "1ESY1160099321",
      "timestamp": "2024-04-01T00:00:00Z",
      "reason": "Turnusablesung",
      "quality": "Abgelesener Wert",
      "value": 5823400,
      "obis_number": "1-0:2.8.0",
      "is_cancelled": false,
      "created": "2024-04-03T11:00:00Z",
      "modified": "2024-04-03T11:00:00Z"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.