Querying data

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). 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). 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

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.

CSV export of a Thing's or a Place's metrics is coming soon to the v2 API.

Response shape

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

[
  {
    "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.

A standalone manufacturer/model catalog endpoint is coming soon to the v2 API.

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.