Skip to main content

Battery control guide

Description​

Control your battery using the Clevergy Connect API: check status, view charge level, and schedule charge/discharge actions.

info

You need your Clevergy API key. Contact us if you haven't received it yet.

Step 1: Get your battery equipment​

Retrieve available batteries by filtering for STORAGE type equipment.

API Reference: Get Tenant Equipments

Request:​

curl -L 'https://connect.clever.gy/equipments?integrationType=STORAGE' \
-H 'Accept: application/json' \
-H 'clevergy-api-key: <your-api-key>'

Response:​

{
  "cursor": null,
  "elements": [
    {
      "equipmentId": "eq_abc123def456",
      "integrationId": "int_789xyz012",
      "vendor": "HUAWEI_OAUTH"
    }
  ]
}

Copy the equipmentId - you'll need it for all following requests.

Step 2: Check battery specifications​

Get technical details: status, capacity, max power.

API Reference: Get Storage Equipment

Request:​

curl -L 'https://connect.clever.gy/equipments/eq_abc123def456/storage' \
-H 'Accept: application/json' \
-H 'clevergy-api-key: <your-api-key>'

Response:​

{
  "status": "ACTIVE",
  "maxChargePower": 5000,
  "maxDischargePower": 5000,
  "ratedCapacity": 15
}
  • maxChargePower / maxDischargePower: Max power in W (5000W = 5kW)
  • ratedCapacity: Capacity in kWh

Step 3: Check battery charge level (SOC)​

SOC (State of Charge) shows battery percentage over a date range. Data updates every 5 minutes.

API Reference: Get Storage Equipment SOC

Request:​

curl -L 'https://connect.clever.gy/equipments/eq_abc123def456/storage/soc?startDate=2025-10-14T00:00:00&endDate=2025-10-14T23:00:00' \
-H 'Accept: application/json' \
-H 'clevergy-api-key: <your-api-key>'

Date format: YYYY-MM-DDTHH:MM:SS (UTC timezone)

warning

All timestamps are in UTC. For Spain (UTC+2): 14:00:00 UTC = 16:00:00 local time.

Response:​

[
  {
    "time": "2025-10-14T13:35:00",
    "soc": 80
  },
  {
    "time": "2025-10-14T13:40:00",
    "soc": 82
  }
]
  • time: Measurement timestamp (UTC)
  • soc: Battery charge % (0-100)

Step 4: Schedule battery actions​

Schedule charge, discharge, or pause actions.

API Reference: Schedule Storage Equipment Action

Request:​

curl -L 'https://connect.clever.gy/equipments/eq_abc123def456/storage/schedule' \
-H 'Content-Type: application/json' \
-H 'clevergy-api-key: <your-api-key>' \
-d '{REQUEST_BODY}'

Parameters​

Required:

  • action: CHARGE, DISCHARGE, or PAUSE

Optional:

  • targetSOC: Target charge % (0-100)
  • dispatchTimeMins: Time in minutes to complete
  • powerKWDispatch: Charge/discharge power in kW

Use cases with request bodies​

1. Nighttime charge (valley tariff)​

Charge overnight to 80% over 5 hours during cheap electricity hours.

{
  "actions": [
    {
      "date": "2025-10-14T01:00:00.000Z",
      "action": "CHARGE",
      "targetSOC": 80,
      "dispatchTimeMins": 300
    }
  ]
}

2. Peak hour discharge​

Discharge at 3kW during peak electricity prices.

{
  "actions": [
    {
      "date": "2025-10-14T18:00:00.000Z",
      "action": "DISCHARGE",
      "powerKWDispatch": 3
    }
  ]
}

3. Solar optimization​

Charge from solar surplus, discharge during peak hours, recharge at night.

{
  "actions": [
    {
      "date": "2025-10-14T08:00:00.000Z",
      "action": "CHARGE",
      "targetSOC": 100
    },
    {
      "date": "2025-10-14T18:00:00.000Z",
      "action": "DISCHARGE",
      "targetSOC": 20
    },
    {
      "date": "2025-10-14T22:00:00.000Z",
      "action": "CHARGE"
    }
  ]
}

4. Full day schedule​

Complete daily management: charge overnight, pause morning, use solar midday, discharge peak hours.

{
  "actions": [
    {
      "date": "2025-10-14T01:00:00.000Z",
      "action": "CHARGE",
      "targetSOC": 100,
      "dispatchTimeMins": 300
    },
    {
      "date": "2025-10-14T08:00:00.000Z",
      "action": "PAUSE"
    },
    {
      "date": "2025-10-14T12:00:00.000Z",
      "action": "CHARGE"
    },
    {
      "date": "2025-10-14T18:00:00.000Z",
      "action": "DISCHARGE",
      "targetSOC": 30,
      "powerKWDispatch": 3
    }
  ]
}