Query your first building

What you’ll learn

This guide walks through querying a building from scratch: authenticating, discovering what’s available, and exploring the building graph. By the end, you’ll understand the basic query patterns for working with building data.

Prerequisites

A Tacit API key (get one here)
A building connected to your account

Step 1: Set up your environment

export TACIT_API_KEY="YOUR_API_KEY"
export TACIT_GRAPHQL="https://app.betacit.com/graphql"

import requests

API_KEY = "YOUR_API_KEY"
GRAPHQL_URL = "https://app.betacit.com/graphql"

def query(q, variables=None):
    response = requests.post(
        GRAPHQL_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"query": q, "variables": variables or {}}
    )
    return response.json()["data"]

const API_KEY = "YOUR_API_KEY";
const GRAPHQL_URL = "https://app.betacit.com/graphql";

async function query(q: string, variables?: Record<string, unknown>) {
  const res = await fetch(GRAPHQL_URL, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: q, variables }),
  });
  const json = await res.json();
  return json.data;
}

Step 2: Discover your buildings

Every query requires a siteId that scopes it to your site. You’ll find this in your Tacit dashboard. Then search by name, no need to know building IDs:

{ building(siteId: "your-site-id", name: "Pool") { id name type } }

curl -X POST $TACIT_GRAPHQL \
  -H "Authorization: Bearer $TACIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ building(siteId: \"your-site-id\", name: \"Pool\") { id name type } }"}'

SITE_ID = "your-site-id"
data = query('{ building(siteId: "%s", name: "Pool") { id name type } }' % SITE_ID)
for b in data["building"]:
    print(f"{b['id']}: {b['name']}")

const SITE_ID = "your-site-id";
const data = await query(`{ building(siteId: "${SITE_ID}", name: "Pool") { id name type } }`);
data.building.forEach((b) => console.log(`${b.id}: ${b.name}`));

All root queries require siteId. For brevity, remaining examples in this guide omit it, but it’s always required.

{
  "data": {
    "building": [
      { "id": "B001", "name": "One Pool Street", "type": "Building" }
    ]
  }
}

Step 3: Explore the spatial hierarchy

See how the building is organized (wings, floors, and zones):

{
  building(siteId: "your-site-id", id: "B001") {
    name
    locations {
      name
      type
      locations {
        name
        type
      }
    }
  }
}

Step 4: Find equipment by name or type

Search for equipment without knowing UUIDs:

# By name: finds all AHUs (siteId required on all root queries)
{ equipment(siteId: "your-site-id", name: "AHU") { name type location { name } } }

# By Brick class: all HVAC equipment (AHUs, VAVs, chillers, etc.)
{ equipment(siteId: "your-site-id", is: "HVAC_Equipment") { name type } }

# A specific piece of equipment
{ equipment(siteId: "your-site-id", id: "TE01-XX-AHU-001") { name type } }

Cross-cutting: equipment in a location

Find VAVs in the Library without knowing any IDs:

{
  equipment(siteId: "your-site-id", locationName: "Library", is: "VAV") {
    name
    type
    location { name }
  }
}

{
  "data": {
    "equipment": [
      { "name": "TW01-LBR-RPC-01", "type": "VAV", "location": { "name": "Library" } },
      { "name": "TW01-LBR-RPC-02", "type": "VAV", "location": { "name": "Library" } }
    ]
  }
}

Step 5: Read points on equipment

Query the points (sensors, setpoints, commands) on a piece of equipment:

{
  equipment(siteId: "your-site-id", id: "TE01-XX-AHU-001") {
    name
    points {
      name
      type
      unit
    }
  }
}

Filter to just temperature sensors:

{
  equipment(siteId: "your-site-id", id: "TE01-XX-AHU-001") {
    name
    points(is: "Temperature_Sensor") {
      name
      type
      unit
    }
  }
}

Step 6: Trace equipment chains

A single query that shows an AHU, its sensors, and the downstream VAVs it feeds:

{
  equipment(siteId: "your-site-id", id: "TE01-XX-AHU-001") {
    name
    points(is: "Temperature_Sensor") {
      name
      type
      unit
    }
    downstream {
      name
      type
      points(is: "Zone_Air_Temperature_Sensor") {
        name
        unit
      }
    }
  }
}

This is one request. No loops, no pagination, no client-side assembly.

Next steps

Find equipment by type

Master the class hierarchy with more examples.

Traverse equipment chains

Use upstream and downstream to trace dependencies.

Getting started

Core concepts

Guides

Query your first building

What you’ll learn

Prerequisites

Step 1: Set up your environment

Step 2: Discover your buildings

Step 3: Explore the spatial hierarchy

Step 4: Find equipment by name or type

Cross-cutting: equipment in a location

Step 5: Read points on equipment

Step 6: Trace equipment chains

Next steps

Find equipment by type

Traverse equipment chains

​What you’ll learn

​Prerequisites

​Step 1: Set up your environment

​Step 2: Discover your buildings

​Step 3: Explore the spatial hierarchy

​Step 4: Find equipment by name or type

​Cross-cutting: equipment in a location

​Step 5: Read points on equipment

​Step 6: Trace equipment chains

​Next steps

Find equipment by type

Traverse equipment chains

What you’ll learn

Prerequisites

Step 1: Set up your environment

Step 2: Discover your buildings

Step 3: Explore the spatial hierarchy

Step 4: Find equipment by name or type

Cross-cutting: equipment in a location

Step 5: Read points on equipment

Step 6: Trace equipment chains

Next steps