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

# Readings API

> Observe the state of an Entity over time.

<Frame>
  <img src="https://mintcdn.com/realto/EG-Ok6q3nUjGJxIo/images/readings.jpg?fit=max&auto=format&n=EG-Ok6q3nUjGJxIo&q=85&s=e6261919201cf17bded569acf23ba8cc" alt="illustration related to readings" width="1600" height="800" data-path="images/readings.jpg" />
</Frame>

A Reading captures a snapshot of an Entity's state. We periodically create Readings for each Entity to track how their state changes over time.

Entities of the same type produce similarly structured Readings, allowing you to process them uniformly regardless of their manufacturer.

## What makes Readings useful

Our Readings API is built for performance and designed to handle large volumes of data.

Because Readings are consistent and normalized across all Entities, they provide a solid foundation for building real-time experiences, reporting tools, and cloud-based services that interact with your devices.

And in most cases, Readings are stored indefinitely. This gives you long-term access to historical data, ideal for building timelines, tracking changes, and powering applications that rely on deeper analysis.

## What you’ll need

* A valid access (bearer) token
* An Entity of any type
  ​

## Let's try it out

Use the <Tooltip tip="The ID of the Entity.">entityId</Tooltip> to [List all Readings](/api-reference/endpoint/readings-api/readings/retrieves-readings) for it.

You'll also have to specify a <Tooltip tip="The start of the time frame (UTC).">start</Tooltip> date. Readings that came in before this time won't be part of the response.

<ParamField body="start" type="string" required />

The [Reading Object](/api-reference/endpoint/readings-api/readings/reading-object) for your Entity might look different from the one in the example below.

```json Response (Body) [expandable] theme={null}
{
    "data": [
        {
            "id": "71795703-1d72-[...]",
            "entityId": "bd297b95-5579-[...]",
            "measured": "2024-09-03T02:06:39Z",
            "received": "2024-09-03T02:06:44.6020711Z",
            "processed": "2024-09-03T02:06:44.9891195Z",
            "data": {
                "instantaneousCurrent": {
                    "l1": 2.95,
                    "total": 2.95,
                    "unit": "A"
                },
                "instantaneousVoltage": {
                    "l1": 242.3,
                    "total": 242.3,
                    "unit": "V"
                },
                "negativeActiveEnergy": {
                    "t1": 12794452,
                    "t2": 5067134,
                    "total": 17861586,
                    "unit": "Wh"
                },
                "negativeActiveInstantaneousPower": {
                    "total": 715,
                    "unit": "W"
                },
                "positiveActiveEnergy": {
                    "t1": 6538224,
                    "t2": 8590571,
                    "total": 15128795,
                    "unit": "Wh"
                },
                "positiveActiveInstantaneousPower": {
                    "total": 0,
                    "unit": "W"
                }
            }
        }, ...
    ]
}

```

<Warning>
  <span className="font-semibold">Caution</span>\
  The <Tooltip tip="The charge location in latitude and longitude coordinates.">location</Tooltip> object might not be available to you. However, our [Location Matching](/guides/location-matching) feature is a privacy-friendly alternative available to all users.
</Warning>