---
title: "Querying data"
description: "How to read telemetry back out (raw, aggregated, and exported)"
icon: "magnifying-glass-chart"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

You read telemetry back through the v2 query endpoints: raw readings, aggregates over time
windows, and latest snapshots.

> **Prerequisites:** an API key with `read` scopes covering the Things and places you query
> (see [Resource filters](/platform/resource-filters)). The query endpoints are served under
> the `/v2` path. The **API Reference** is the authoritative spec for exact parameters and
> response fields.

## Endpoint paths

Reads come in two scopes:

- **Per-Thing**, keyed by `{thingId}`: `GET /v2/things/{thingId}/timeseries` returns one
  Thing's data.
- **Place-wide**, scoped to a Place and its `{placeId}`: `GET /v2/sites/{placeId}/timeseries`
  aggregates all Things in the Place. Use `/v2/fleets/{placeId}/…` for a Fleet.

`{placeId}` is a GUID (sites and fleets), and `{thingId}` is a GUID.

## Raw vs. binned

Time-series endpoints work in two modes:

- **Raw**: every individual reading in the window. Capped at a **24-hour** window to keep
  responses bounded.
- **Binned (aggregated)**: readings bucketed into intervals (per minute/hour/day), with
  each metric rolled up using its aggregation. Controlled by **`binUnit`** + **`binValue`**,
  which must be supplied **together or not at all**.

Each metric is aggregated by its `defaultAggregation` (see
[Data model](/platform/data-model#metric-definition)). For example, `soc`
returns its `Last` value per bucket, an energy counter its `Sum`.

## Common query parameters

| Parameter | Meaning |
|-----------|---------|
| `startTime`, `endTime` | The window, as ISO 8601 timestamps. |
| `binUnit`, `binValue` | Bucket size for aggregation (e.g. `h` + `1`). Defaults to `h` + `1`. |
| `selectedFields` | The metric ids to return. Omit for all. Place-level metric queries are capped at **20** metrics. |

## Core endpoints

### A single Thing's time series

```http
GET /v2/things/{thingId}/timeseries?startTime=2026-06-20T00:00:00Z&endTime=2026-06-20T23:59:59Z&binUnit=h&binValue=1&selectedFields=soc,moduleVoltage
```

Returns time-bucketed points for one Thing. Drop `binUnit`/`binValue` for raw readings
(remember the 24-hour cap on raw).

| Endpoint | Returns |
|----------|---------|
| `GET /v2/things/{thingId}/timeseries` | Binned (or raw) series for one Thing. |
| `GET /v2/things/{thingId}/events` | Events for one Thing (raw (≤24h) or binned). |

### Place-wide time series

Place-wide endpoints take a `sites` or `fleets` segment plus the Place `{placeId}`.

| Endpoint | Returns |
|----------|---------|
| `GET /v2/sites/{placeId}/timeseries` | Aggregated series across all Things in the Place. |
| `GET /v2/sites/{placeId}/timeseries/metrics` | The same, restricted to specific metric ids (≤20). |

### Summaries

When you want one aggregated number per metric over a window rather than a series:

| Endpoint | Returns |
|----------|---------|
| `GET /v2/things/{thingId}/summary` | One aggregated value per metric for a Thing. |
| `GET /v2/sites/{placeId}/summary` | Place-wide aggregated summary. |
| `GET /v2/sites/{placeId}/summary/metrics` | Summary for specific metrics (≤20). |

### Latest snapshots & recent data

| Endpoint | Returns |
|----------|---------|
| `GET /v2/things/{thingId}/latest-event` | The single most recent reading. |
| `GET /v2/things/{thingId}/recent-events` | The N latest events within a lookback window (1–30 days). |
| `GET /v2/things/{thingId}/recent-data` | Latest snapshot, with an optional cutoff time. |
| `GET /v2/things/{thingId}/latest-event-time` | Just the timestamp of the latest reading. |

### Counts

| Endpoint | Returns |
|----------|---------|
| `GET /v2/things/{thingId}/count` | Count of raw events in a window. |

<Note>CSV export of a Thing's or a Place's metrics is **coming soon** to the v2 API.</Note>

## Response shape

Time-series and event endpoints return a list of **points**, each a timestamp plus the
metric values at that time:

```json
[
  {
    "time": "2026-06-20T12:00:00Z",
    "timeInHours": 12,
    "groupBy": null,
    "dataPoints": [
      { "type": "soc",           "unit": "%", "value": 87.4, "aggregation": "Last" },
      { "type": "moduleVoltage", "unit": "V", "value": 52.3, "aggregation": "Last" }
    ]
  }
]
```

- `type` is the metric name; `value` is the reading; `unit` comes from the Metric Definition.
- `aggregation` appears on aggregated/summary responses to tell you how `value` was computed;
  it's omitted on raw responses.

## Metadata endpoints

To build queries dynamically, read your ontology and integration metadata from the v2 API:

| Endpoint | Returns |
|----------|---------|
| `GET /v2/definitions/metrics` | Metric definitions: data type, unit, and default aggregation. |
| `GET /v2/definitions/thing-types` | Thing-type definitions, including their property schemas. |
| `GET /v2/integrations/mapping` | Integration types and their resources. |

<Note>A standalone manufacturer/model catalog endpoint is **coming soon** to the v2 API.</Note>

## Guardrails

- **Raw queries are capped at a 24-hour window.** For longer spans, use binned mode.
- **Place-level metric queries are capped at 20 metrics** to prevent expensive fan-out.
- **`binUnit` and `binValue` are all-or-nothing**: supply both for aggregation, or neither
  for raw mode.

## Recap

Pick the endpoint by the shape you need: a **series** (`/v2/things/{thingId}/timeseries` or
`/v2/sites/{placeId}/timeseries`), a **single number per metric**
(`/v2/things/{thingId}/summary`), or **the latest reading**
(`/v2/things/{thingId}/latest-event`). Use raw mode for short, high-resolution windows and
binned mode for anything longer. The **API Reference** documents the exact parameters and
response fields for each.