Aggregating list results over time

The charger, location, and charging-session list endpoints can attach time-bucketed metrics to each returned resource. Use this when a dashboard needs a trend per charger, location, or session alongside the records themselves. It is not a single grand-total endpoint: the normal list response remains, with an aggregations array attached to each resource that has matching data.

Choose a measure and field

Set aggregate to one or more comma-separated function:field expressions. Supported functions are count, sum, avg, min, and max; all except count require a numeric field. Nested metrics use a dotted field path, such as sessions.energy. The allowed field paths differ by operation; use that operation’s aggregate parameter as the allowlist. For example, GET /locations supports sum:sessions.energy.

Choose a fixed interval

aggregate_interval is required whenever aggregate is set. Use a positive integer followed by s, m, h, d, or w, such as 15m, 1h, or 1d. These are fixed durations, not calendar-aligned periods; 1w means seven 24-hour days. Bucket timestamps are UTC.

Request daily energy by location

curl --get "$API_BASE/locations" \
  --data-urlencode 'aggregate=sum:sessions.energy' \
  --data-urlencode 'aggregate_interval=1d' \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=100' \
  --header "Authorization: Bearer $API_KEY" \
  --header "organization-id: $ORGANIZATION_ID" \
  --header "compatibility-date: $COMPATIBILITY_DATE" \
  --header 'Accept: application/json'

A simplified response for one location looks like this:

{
  "locations": [
{
  "aggregations": [
    {
      "bucketStart": "2026-10-25T00:00:00.000Z",
      "metrics": {
        "sum.sessions.energy": 42.7
      }
    }
  ]
}
  ],
  "count": 1
}

On GET /locations, sum:sessions.energy buckets each location’s session energy by session stoppedAt; other measures bucket by their own time field. The list filter still uses the parent endpoint’s allowlisted fields and does not add an independent from/to window for the buckets. Use the operation reference to verify the time field for the measure you choose.

Pagination still applies to resource records, not to time buckets, and count or total continues to describe the matching parent records. To calculate an organization-wide total, combine the per-resource bucket metrics in your application.