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

# Heat Pump State

> Read-only state data and current readings from heat pump devices

# Heat Pump State

Heat pump state parameters provide real-time sensor readings and current device status. These fields are read-only and automatically updated from the manufacturer's API.

<Note>
  State data refresh frequency depends on the manufacturer's API. Most values update every 5-15 minutes.
</Note>

## Operational Status

<ResponseField name="current_power_consumption_w" type="integer">
  Current power consumption in Watts.

  **Example:** `2341`
</ResponseField>

<ResponseField name="current_mode" type="enum">
  The optimization mode Podero is running the heat pump at right now. This reflects the actual real-time operation and may vary from `optimization_level` as the system responds to spot prices. Only meaningful when `is_smart_optimization_active` is `true`.

  **Options:** `min`, `low`, `mid`, `max`

  **Example:** `mid`
</ResponseField>

<ResponseField name="current_state_last_updated_at" type="datetime">
  Timestamp when the device state was last updated from the manufacturer's API.

  Use this to determine data freshness.

  **Example:** `2023-03-22T13:54:34.000Z`
</ResponseField>

## Temperature Readings

<ResponseField name="outdoor_temperature" type="float">
  Current outdoor temperature in °C measured by the heat pump.

  **Example:** `9.3`
</ResponseField>

<ResponseField name="indoor_actual_temperature" type="float">
  Current indoor temperature in °C (if indoor sensor is available).

  May be `null` if the device doesn't have an indoor temperature sensor.

  **Example:** `21.2`
</ResponseField>

<ResponseField name="indoor_target_temperature" type="float">
  Target indoor temperature in °C requested by the heating system.

  May be `null` if not reported by the device.

  **Example:** `22.0`
</ResponseField>

<ResponseField name="indoor_target_temperature_offset" type="float">
  Offset applied to the indoor target temperature in °C. Podero uses this to steer heating up or down relative to the user's base target.

  **Example:** `1.5`
</ResponseField>

<ResponseField name="optimization_level" type="enum">
  The configured optimization aggressiveness for this heat pump — the ceiling Podero will operate at.

  **Options:** `Low`, `Mid`, `Max`

  **Example:** `Mid`
</ResponseField>

<ResponseField name="inlet_temperature" type="float">
  Temperature of the heating circuit water entering the heat pump in °C.

  **Example:** `35.4`
</ResponseField>

<ResponseField name="outlet_temperature" type="float">
  Temperature of the heating circuit water leaving the heat pump in °C.

  **Example:** `42.1`
</ResponseField>

<ResponseField name="dhw_temperature" type="float">
  Current temperature of domestic hot water in °C.

  **Example:** `51.1`
</ResponseField>

<ResponseField name="dhw_standard_temperature" type="float">
  Domestic hot water setpoint temperature in °C as reported by the device.

  **Example:** `48.0`
</ResponseField>

## Usage Examples

### Get Device State

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{device_id}' \
    -H 'Authorization: Bearer {auth_token}' \
    -H 'Accept: application/json'
  ```

  ```python Python theme={null}
  response = requests.get(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{device_id}',
      headers={
          'Authorization': f'Bearer {auth_token}',
          'Accept': 'application/json'
      }
  )

  device = response.json()

  # Access state fields
  current_power = device['current_power_consumption_w']
  indoor_temp = device['indoor_actual_temperature']
  dhw_temp = device['dhw_temperature']
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.podero.com/api/partners/v2.0/org/${orgId}/users/${userId}/heat-pumps/${deviceId}`,
    {
      headers: {
        'Authorization': `Bearer ${authToken}`,
        'Accept': 'application/json'
      }
    }
  );

  const device = await response.json();

  // Access state fields
  const currentPower = device.current_power_consumption_w;
  const indoorTemp = device.indoor_actual_temperature;
  const dhwTemp = device.dhw_temperature;
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Data Polling">
    * Poll device state every 5-15 minutes for dashboard updates
    * Check `current_state_last_updated_at` to avoid unnecessary API calls
    * Implement caching to reduce API load
    * Show last update timestamp to users for transparency
  </Accordion>

  <Accordion title="Temperature Display">
    * Show both indoor and outdoor temperatures for context
    * Highlight when indoor temperature is outside comfort range
    * DHW temperature should typically be 45-55°C
    * Consider outdoor temperature for heating efficiency expectations
  </Accordion>

  <Accordion title="Error Handling">
    * Handle `null` values gracefully (e.g., missing indoor sensor)
    * Display user-friendly messages for stale data
    * Provide troubleshooting steps when data stops updating
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Heat Pump Attributes" icon="sliders" href="/partner-api/reference/heat-pumps/attributes">
    Writable parameters and configuration
  </Card>

  <Card title="Dashboard Integration" icon="chart-line" href="/partner-api/user-journeys/end-user/dashboard-integration">
    Building end-user dashboards
  </Card>
</CardGroup>