Fetch historical data

The typical workflow for historical data is a two-step process:

Find points using the GraphQL API to discover sensors and their IDs
Query timeseries using the REST API to fetch time-value data for those timeseries IDs

Step 1: Find point IDs with GraphQL

Query the knowledge graph to find the points you’re interested in:

{
  point(siteId: "your-site-id", is: "Temperature_Sensor") {
    id
    name
    type
    unit
    timeseriesId
    equipment { name }
  }
}

{
  "data": {
    "point": [
      {
        "id": "TW01-LBR-RPC-01/Space_Temp",
        "name": "TW01-LBR-RPC-01/Space_Temp",
        "type": "Zone_Air_Temperature_Sensor",
        "unit": "DEG_C",
        "timeseriesId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "equipment": { "name": "TW01-LBR-RPC-01" }
      },
      {
        "id": "TW01-LBR-RPC-02/Space_Temp",
        "name": "TW01-LBR-RPC-02/Space_Temp",
        "type": "Zone_Air_Temperature_Sensor",
        "unit": "DEG_C",
        "timeseriesId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "equipment": { "name": "TW01-LBR-RPC-02" }
      }
    ]
  }
}

Step 2: Fetch timeseries for those points

Use the point IDs to query historical data:

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

The response enriches each series with the point’s metadata, so you don’t need to join the results yourself:

{
  "query": {
    "start": "-24h",
    "end": "now()",
    "timezone": "Europe/London",
    "window": "15m",
    "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-27T17:00:00+00:00", "v": 22.1 },
        { "t": "2026-02-27T17:15:00+00:00", "v": 22.3 }
      ]
    },
    {
      "timeseriesId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "TW01-LBR-RPC-02/Space_Temp",
      "type": "Zone_Air_Temperature_Sensor",
      "unit": "degC",
      "equipment": "TW01-LBR-RPC-02",
      "data": [
        { "t": "2026-02-27T17:00:00+00:00", "v": 21.8 },
        { "t": "2026-02-27T17:15:00+00:00", "v": 21.9 }
      ]
    }
  ],
  "errors": {}
}

Timestamps are in the site’s local timezone (here Europe/London, UTC+0), declared in query.timezone.

Common patterns

Dashboard: latest value for all equipment points

Get the current values for all points on a piece of equipment, directly in one GraphQL call:

{
  equipment(siteId: "your-site-id", name: "TW01-LBR-AHU-01", nameMatch: CONTAINS) {
    points {
      name
      type
      unit
      timeseriesId
      currentValue { value timestamp quality }
    }
  }
}

Analytics: weekly energy comparison

{
  "timeseriesIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "start": "-7d",
  "window": "1d",
  "aggregate": "sum"
}

Fault detection: high-resolution recent data

{
  "timeseriesIds": ["b2c3d4e5-f6a7-8901-bcde-f12345678901", "c3d4e5f6-a7b8-9012-cdef-123456789012"],
  "start": "-2h",
  "limit": 5000
}

This returns raw (unaggregated) data for the last 2 hours, useful for detecting oscillation, stuck sensors, or control issues.

Python example

import requests

API_KEY = "your-api-key"
SITE_ID = "your-site-id"

# Step 1: Find temperature sensors via GraphQL
gql_resp = requests.post(
    f"https://app.betacit.com/graphql",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "query": """
        { point(siteId: "%s", is: "Temperature_Sensor") { id name unit timeseriesId } }
        """ % SITE_ID
    },
)
points = gql_resp.json()["data"]["point"]
timeseries_ids = [p["timeseriesId"] for p in points]

# Step 2: Fetch 24h history with 15-min aggregation
ts_resp = requests.post(
    f"https://app.betacit.com/api/v1/sites/{SITE_ID}/timeseries",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "timeseriesIds": timeseries_ids,
        "start": "-24h",
        "window": "15m",
        "aggregate": "mean",
    },
)
for series in ts_resp.json()["series"]:
    print(f"{series['name']}: {len(series['data'])} readings")

TypeScript example

import { graphqlClient } from "./client";

const API_KEY = "your-api-key";
const SITE_ID = "your-site-id";

// Step 1: Find points
const { point } = await graphqlClient.request(`
  { point(siteId: "${SITE_ID}", is: "Temperature_Sensor") { id name timeseriesId } }
`);

// Step 2: Fetch timeseries
const res = await fetch(`https://app.betacit.com/api/v1/sites/${SITE_ID}/timeseries`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    timeseriesIds: point.map((p) => p.timeseriesId),
    start: "-24h",
    window: "15m",
  }),
});

const { series, errors } = await res.json();
console.log(`Got ${series.length} series, ${Object.keys(errors).length} errors`);

Getting started

Core concepts

Guides

Fetch historical data

Step 1: Find point IDs with GraphQL

Step 2: Fetch timeseries for those points

Common patterns

Dashboard: latest value for all equipment points

Analytics: weekly energy comparison

Fault detection: high-resolution recent data

Python example

TypeScript example

​Step 1: Find point IDs with GraphQL

​Step 2: Fetch timeseries for those points

​Common patterns

​Dashboard: latest value for all equipment points

​Analytics: weekly energy comparison

​Fault detection: high-resolution recent data

​Python example

​TypeScript example

Step 1: Find point IDs with GraphQL

Step 2: Fetch timeseries for those points

Common patterns

Dashboard: latest value for all equipment points

Analytics: weekly energy comparison

Fault detection: high-resolution recent data

Python example

TypeScript example