> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nox.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Thermal Control Current State

> Get the current thermal state of a specific device.

This returns the most recent 15-minute snapshot of the thermal model state for both the
**domestic hot water (DHW) tank** and the **house** (space heating/cooling). It reflects the latest
known thermal energy flows, temperatures, and heat pump power consumption.

**Tank fields:**
 * `Y` (kWh mode only) — Current energy state of the DHW tank.
 * `DHW_temperature` — Current domestic hot water temperature in °C (always present).
 * `Q_loss` / `Q_gain` (kW) or `T_loss` / `T_gain` (°C) — Thermal loss to the environment and gain per activation level.
 * `P_if_activated` — Electrical power consumption (kW) per activation level if the heat pump is activated for DHW.

**House fields:**
 * `Y` (kWh mode only) — Current energy state of the house.
 * `Space_temperature` (celsius mode only) — Current room temperature in °C.
 * `Q_natural` / `Q_heating` / `Q_cooling` (kW) or `T_natural` / `T_heating` / `T_cooling` (°C) — Natural thermal drift, and heating/cooling effect per activation level.
 * `P_heating` / `P_cooling` — Electrical power consumption (kW) per activation level for space heating and cooling.

Use the `unit` query parameter to choose between energy values (`kWh`, default) or temperature equivalents (`celsius` / °C).
In celsius mode, bounds are returned in °C and thermal flows as temperature change rates (°C per 15min) instead of energy (kWh/kW).
Power fields (`P_*`) are always returned in kW regardless of the unit choice.

The timestamp refers to the data that will happen in the next 15 minutes after the timestamp. All timestamps are in UTC.



## OpenAPI

````yaml /api-docs/supplier-control/openapi-thermal-control.json get /v1/device/thermal-control/current-state
openapi: 3.1.0
info:
  title: NOX Energy API - Thermal Control
  description: >
    # Thermal Control API Documentation


    This documentation shows only the endpoints available to thermal control
    users.


    ## Authentication


    1. Get your API key from [NOX Energy](mailto:support@nox.energy).

    2. Include the API key in your API calls with the header: `x-api-key:
    YOUR_API_KEY`.


    ## Access Level


    This documentation is specifically for **thermal control users** who have
    access to these endpoints.


    Base URL: [https://api.nox.energy](https://api.nox.energy)
  version: 1.0.0
servers:
  - url: https://api.nox.energy
    description: Production Server
security:
  - ApiKeyAuth: []
tags:
  - name: Asset Info
    description: API to get basic information about your assets.
  - name: Device Consumption
    description: API to get consumption data of your devices.
  - name: Thermal Control
    description: API for thermal control specific endpoints.
  - name: User Management
    description: API endpoints to manage users and their data.
paths:
  /v1/device/thermal-control/current-state:
    get:
      tags:
        - Thermal Control
      summary: Get Thermal Control Current State
      description: >-
        Get the current thermal state of a specific device.


        This returns the most recent 15-minute snapshot of the thermal model
        state for both the

        **domestic hot water (DHW) tank** and the **house** (space
        heating/cooling). It reflects the latest

        known thermal energy flows, temperatures, and heat pump power
        consumption.


        **Tank fields:**
         * `Y` (kWh mode only) — Current energy state of the DHW tank.
         * `DHW_temperature` — Current domestic hot water temperature in °C (always present).
         * `Q_loss` / `Q_gain` (kW) or `T_loss` / `T_gain` (°C) — Thermal loss to the environment and gain per activation level.
         * `P_if_activated` — Electrical power consumption (kW) per activation level if the heat pump is activated for DHW.

        **House fields:**
         * `Y` (kWh mode only) — Current energy state of the house.
         * `Space_temperature` (celsius mode only) — Current room temperature in °C.
         * `Q_natural` / `Q_heating` / `Q_cooling` (kW) or `T_natural` / `T_heating` / `T_cooling` (°C) — Natural thermal drift, and heating/cooling effect per activation level.
         * `P_heating` / `P_cooling` — Electrical power consumption (kW) per activation level for space heating and cooling.

        Use the `unit` query parameter to choose between energy values (`kWh`,
        default) or temperature equivalents (`celsius` / °C).

        In celsius mode, bounds are returned in °C and thermal flows as
        temperature change rates (°C per 15min) instead of energy (kWh/kW).

        Power fields (`P_*`) are always returned in kW regardless of the unit
        choice.


        The timestamp refers to the data that will happen in the next 15 minutes
        after the timestamp. All timestamps are in UTC.
      operationId: >-
        get_thermal_control_current_state_v1_device_thermal_control_current_state_get
      parameters:
        - name: device_id
          in: query
          required: true
          schema:
            type: string
            description: |

              The ID of the device.
            title: Device Id
          description: |

            The ID of the device.
        - name: unit
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Unit'
            description: |+

              Unit for thermal values returned in the response. 

              'kWh' (default) returns energy in kWh and power in kW. 

              'celsius' returns temperature equivalents in °C. 

            default: kWh
          description: |+

            Unit for thermal values returned in the response. 

            'kWh' (default) returns energy in kWh and power in kW. 

            'celsius' returns temperature equivalents in °C. 

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: {}
              examples:
                kWh:
                  summary: Response with unit=kWh (default)
                  value:
                    data:
                      device_id: HP123456
                      timestamp: '2025-01-15 12:15:12'
                      tank:
                        'Y': 25.12
                        DHW_temperature: 47
                        Q_loss: 0.25
                        Q_gain:
                          - 16.35
                          - 16.35
                          - 16.35
                          - 16.35
                        P_if_activated:
                          - 2.38
                          - 2.87
                          - 3.18
                          - 3.31
                      house:
                        'Y': 521.76
                        Q_natural: -2.04
                        Q_heating:
                          - 8.26
                          - 8.26
                          - 8.26
                          - 8.26
                          - 8.26
                          - 8.26
                          - 8.26
                          - 8.26
                        Q_cooling:
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                        P_heating:
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                        P_cooling:
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                    meta:
                      timestamp_time_zone: UTC
                      temperature_unit: °C
                      tank_Y_unit: kWh
                      tank_Q_loss_unit: kW
                      tank_Q_gain_unit: kW
                      tank_P_unit: kW
                      house_Y_unit: kWh
                      house_Q_natural_unit: kW
                      house_Q_heating_unit: kW
                      house_Q_cooling_unit: kW
                      house_P_heating_unit: kW
                      house_P_cooling_unit: kW
                      energy_supplier: Energy Supplier A
                celsius:
                  summary: Response with unit=celsius
                  value:
                    data:
                      device_id: HP123456
                      timestamp: '2025-01-15 12:15:12'
                      tank:
                        DHW_temperature: 47
                        T_loss: 0.12
                        T_gain:
                          - 7.65
                          - 7.65
                          - 7.65
                          - 7.65
                        P_if_activated:
                          - 2.38
                          - 2.87
                          - 3.18
                          - 3.31
                      house:
                        Space_temperature: 22
                        T_natural: -0.021
                        T_heating:
                          - 0.087
                          - 0.087
                          - 0.087
                          - 0.087
                          - 0.087
                          - 0.087
                          - 0.087
                          - 0.087
                        T_cooling:
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                        P_heating:
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                          - 1.8
                        P_cooling:
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                          - 0
                    meta:
                      timestamp_time_zone: UTC
                      temperature_unit: °C
                      tank_DHW_temperature_unit: °C
                      tank_T_loss_unit: °C
                      tank_T_gain_unit: °C
                      tank_P_unit: kW
                      house_Space_temperature_unit: °C
                      house_T_natural_unit: °C
                      house_T_heating_unit: °C
                      house_T_cooling_unit: °C
                      house_P_heating_unit: kW
                      house_P_cooling_unit: kW
                      energy_supplier: Energy Supplier A
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Unit:
      type: string
      enum:
        - kWh
        - celsius
      title: Unit
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key authentication. Enter your API key in the format: YOUR_API_KEY'

````