> ## 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.

# Solar Inverter State

> Read-only state data and current readings from solar inverters

# Solar Inverter State

Solar inverter state parameters provide real-time production data, battery status, household consumption, and energy metrics. 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>

## Grid Exchange

<ResponseField name="current_power_to_grid_w" type="integer">
  Current power being exported to or imported from the grid in Watts. Positive values indicate export; negative values indicate import.

  **Example:** `2500` (exporting 2.5 kW)
</ResponseField>

## Solar Production

<ResponseField name="current_solar_production_w" type="integer">
  Current solar power production in Watts.

  Returns `0` during nighttime or cloudy conditions.

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

## Household Consumption

<ResponseField name="household_consumption_w" type="integer">
  Current total power consumption of the household in Watts.

  Includes all electrical loads in the building.

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

## Solar Surplus

<ResponseField name="solar_surplus_w" type="integer">
  Solar power available after household consumption, in Watts. Represents excess production not consumed by the home.

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

## Battery Status

<ResponseField name="battery_charge_level_percent" type="integer">
  Current battery charge level in percent.

  Returns `null` or `0` if no battery is connected.

  **Example:** `85`

  **Range:** 0-100
</ResponseField>

<ResponseField name="battery_charge_discharge_power_w" type="integer">
  Current battery power flow in Watts.

  **Positive values:** Battery is discharging
  **Negative values:** Battery is charging

  **Example:** `-755` (charging at 755W)
</ResponseField>

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

  Use this to determine data freshness.

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

## Usage Examples

### Get Inverter State

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/inverters/{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}/inverters/{device_id}',
      headers={
          'Authorization': f'Bearer {auth_token}',
          'Accept': 'application/json'
      }
  )

  inverter = response.json()

  # Access state fields
  solar_production = inverter['current_solar_production_w']
  battery_level = inverter['battery_charge_level_percent']
  consumption = inverter['household_consumption_w']
  ```

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

  const inverter = await response.json();

  // Access state fields
  const solarProduction = inverter.current_solar_production_w;
  const batteryLevel = inverter.battery_charge_level_percent;
  const consumption = inverter.household_consumption_w;
  ```
</CodeGroup>

## Understanding Power Flows

<Tabs>
  <Tab title="Sunny Day - High Production">
    **Scenario:** `current_solar_production_w: 8000`, `household_consumption_w: 1500`

    * 1500W used directly in home
    * 6500W available for battery charging and grid export
    * Battery charges if below max charge limit

    **Battery:** Charging at maximum rate
    **Grid:** Exporting excess power
  </Tab>

  <Tab title="Evening - Battery Discharging">
    **Scenario:** `current_solar_production_w: 0`, `household_consumption_w: 2000`

    * No solar production
    * Battery discharges to meet demand
    * Grid supplements if battery can't meet full demand

    **Battery:** Discharging
    **Grid:** Importing if needed
  </Tab>

  <Tab title="Cloudy - Low Production">
    **Scenario:** `current_solar_production_w: 500`, `household_consumption_w: 1500`

    * 500W from solar used directly
    * 1000W deficit met by battery or grid
    * Battery may discharge if policy allows

    **Battery:** Idle or discharging
    **Grid:** Importing to meet demand
  </Tab>

  <Tab title="Peak Production - Battery Full">
    **Scenario:** `current_solar_production_w: 10000`, `battery_charge_level_percent: 100`

    * Home consumption met from solar
    * Battery at maximum charge
    * All surplus exported to grid

    **Battery:** Full, idle
    **Grid:** Exporting maximum surplus
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Data Polling">
    * Poll inverter state every 5-10 minutes during daylight hours
    * Reduce polling to 15-30 minutes during nighttime
    * Check `current_state_last_updated_at` to avoid unnecessary calls
    * Display last update timestamp for transparency
  </Accordion>

  <Accordion title="Production Display">
    * Show current production prominently during daylight
    * Calculate and show self-consumption percentage using `current_solar_production_w` and `household_consumption_w`
    * Highlight peak production times
  </Accordion>

  <Accordion title="Battery Monitoring">
    * Display battery level with charge/discharge status
    * Show power flow direction (charging/discharging)
    * Alert on unusual battery behavior
    * Track cycling patterns for health monitoring
  </Accordion>

  <Accordion title="Energy Flow">
    * Visualize power flows between solar, battery, and home
    * Calculate and display self-consumption rate
    * Provide historical energy flow analysis
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Inverter Attributes" icon="sliders" href="/partner-api/reference/inverters/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>