Timeseries

Endpoint

POST /api/v1/sites/{siteId}/timeseries

Query historical timeseries data for one or more points. Returns time-value pairs enriched with point metadata from the knowledge graph. For the latest value, use currentValue on the GraphQL Point type instead.

This endpoint uses timeseries IDs from the GraphQL API. First query your building’s points via the point query, then use the returned timeseriesId values to fetch historical data.

Path parameters

Parameter	Type	Description
`siteId`	`string`	Site ID

Request body

Field	Type	Required	Default	Description
`timeseriesIds`	`string[]`	Yes	-	Array of timeseries UUIDs (1–200)
`start`	`string`	No	`"-1h"`	Start of time range. Accepts relative (`-1h`, `-24h`, `-7d`) or ISO-8601
`end`	`string`	No	`"now()"`	End of time range. Accepts relative, ISO-8601, or `now()`
`window`	`string`	No	`null`	Downsampling window (`"5m"`, `"1h"`, `"1d"`). Omit for raw data
`aggregate`	`string`	No	`"mean"`	Aggregation: `mean`, `min`, `max`, `sum`, `count`, `first`, `last`
`limit`	`integer`	No	`1000`	Max records per series (1–10,000)

Response

Field	Type	Description
`query`	`object`	Echo of resolved query parameters
`query.timezone`	`string`	IANA timezone of the site (e.g., `Europe/London`). All timestamps in `data` are in this timezone
`series`	`object[]`	One entry per resolved point, enriched with metadata
`series[].timeseriesId`	`string`	Timeseries UUID
`series[].name`	`string`	Point display name
`series[].type`	`string`	Brick class (e.g., `Zone_Air_Temperature_Sensor`)
`series[].unit`	`string`	Engineering unit (e.g., `degC`)
`series[].equipment`	`string`	Parent equipment name
`series[].data`	`array`	Time-value pairs: `t` (ISO-8601 with UTC offset), `v` (number)
`errors`	`object`	Map of unresolved timeseries IDs to error reasons

Pagination

REST list endpoints (e.g., /api/v1/sites/) support optional pagination via query parameters:

Parameter	Default	Max	Description
`limit`	-	1000	Number of items to return. Omit for all results.
`offset`	0	-	Number of items to skip

When limit is provided, the response is wrapped in a paginated envelope:

{
  "count": 42,
  "next": "https://app.betacit.com/api/v1/sites/?limit=10&offset=10",
  "previous": null,
  "results": [ ... ]
}

Without limit, the response is a plain array.

Status codes

Code	Description
`200`	Success. Partial failures are reported in `errors`, not the status code
`400`	Validation error (missing `timeseriesIds`, invalid `aggregate`, etc.)
`401`	Not authenticated
`403`	No access to this site
`404`	Site not found
`429`	Rate limit exceeded. Check the `Retry-After` header

Examples

cURL

curl -X POST https://app.betacit.com/api/v1/sites/your-site-id/timeseries \
  -H "Authorization: Bearer your-api-key-or-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "timeseriesIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ],
    "start": "-24h",
    "window": "5m",
    "aggregate": "mean"
  }'

Last 24 hours with 5-minute aggregation

Request

{
  "timeseriesIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ],
  "start": "-24h",
  "window": "5m",
  "aggregate": "mean"
}

Response

{
  "query": {
    "start": "-24h",
    "end": "now()",
    "timezone": "Europe/London",
    "window": "5m",
    "aggregate": "mean"
  },
  "series": [
    {
      "timeseriesId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "TW01-LBR-RPC-01/Space_Temp",
      "type": "Zone_Air_Temperature_Sensor",
      "unit": "degC",
      "equipment": "TW01-LBR-RPC-01",
      "data": [
        { "t": "2026-02-28T15:00:00+00:00", "v": 22.1 },
        { "t": "2026-02-28T15:05:00+00:00", "v": 22.3 },
        { "t": "2026-02-28T15:10:00+00:00", "v": 22.5 }
      ]
    },
    {
      "timeseriesId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "TW01-LBR-RPC-01/Space_Temp_SP",
      "type": "Zone_Air_Temperature_Setpoint",
      "unit": "degC",
      "equipment": "TW01-LBR-RPC-01",
      "data": [
        { "t": "2026-02-28T15:00:00+00:00", "v": 22.0 },
        { "t": "2026-02-28T15:05:00+00:00", "v": 22.0 },
        { "t": "2026-02-28T15:10:00+00:00", "v": 22.0 }
      ]
    }
  ],
  "errors": {}
}

Peak temperatures over a week

Request

{
  "timeseriesIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "start": "-7d",
  "window": "1h",
  "aggregate": "max",
  "limit": 168
}

Mixed valid and invalid IDs

When some timeseries IDs don’t resolve, the response includes both results and errors:

Request

{
  "timeseriesIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "00000000-0000-0000-0000-000000000000",
    "not-a-uuid"
  ]
}

Response

{
  "query": { "start": "-1h", "end": "now()", "timezone": "Europe/London" },
  "series": [
    {
      "timeseriesId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "TW01-LBR-RPC-01/Space_Temp",
      "type": "Zone_Air_Temperature_Sensor",
      "unit": "degC",
      "equipment": "TW01-LBR-RPC-01",
      "data": [{ "t": "2026-02-28T16:45:12+00:00", "v": 22.3 }]
    }
  ],
  "errors": {
    "00000000-0000-0000-0000-000000000000": "Point not found",
    "not-a-uuid": "Invalid timeseries ID format"
  }
}

Time format reference

Relative durations: -1h, -6h, -24h, -7d, -30d ISO-8601 timestamps: 2026-02-01T00:00:00Z Special values: now()

Timezone behaviour

Response timestamps are always in the site’s local timezone, declared in query.timezone. The UTC offset is embedded in every timestamp (e.g., +00:00 for London, +01:00 during BST), so you never need to convert manually. When an aggregation window is specified, all timestamps are snapped to the window boundary. For example, with window: "15m", timestamps align to :00, :15, :30, :45 in the site’s local time. Data is stored in UTC internally. The timezone conversion is applied on output only.

Aggregation windows

Use case	`window`	`aggregate`
Dashboard sparkline	`"5m"`	`"mean"`
Hourly report	`"1h"`	`"mean"`
Daily peak analysis	`"1d"`	`"max"`
Energy totals	`"1h"`	`"sum"`
Raw data export	omit	-

GraphQL

REST API

REST guides

Endpoint

Path parameters

Request body

Response

Status codes

Examples

cURL

Last 24 hours with 5-minute aggregation

Peak temperatures over a week

Mixed valid and invalid IDs

Time format reference

Timezone behaviour

Aggregation windows

​Endpoint

​Path parameters

​Request body

​Response

​Pagination

​Status codes

​Examples

​cURL

​Last 24 hours with 5-minute aggregation

​Peak temperatures over a week

​Mixed valid and invalid IDs

​Time format reference

​Timezone behaviour

​Aggregation windows

Endpoint

Path parameters

Request body

Response

Pagination

Status codes

Examples

cURL

Last 24 hours with 5-minute aggregation

Peak temperatures over a week

Mixed valid and invalid IDs

Time format reference

Timezone behaviour

Aggregation windows