Skip to main content

​
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"

​
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 } }"}'
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.