Skip to content
/
List status logs for a ho...

List status logs for a home battery

Request

List the historical status logs for a specific home battery. Used to find out the state of the battery at each point it reported in to ev.energy.

Security
oauth2(Required scopes: home_battery:read)
Path
home_battery_idstringrequired

The ID of the specific Home Battery to retrieve status logs for.

Query
page_beforestring[a-z]{4}[A-Z\d]{26}

Return results from the page after this ID.

Example:page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_afterstring[a-z]{4}[A-Z\d]{26}

Return results from the page before this ID.

Example:page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_sizeinteger, [ 1 .. 100 ]

Specify the number of results to return per page.

Default:25
Example:page_size=10
sampled_at__gtestring, (date-time)

Filters for logs sampled at or after this datetime.

Example:sampled_at__gte=2024-04-17T09:39:45.984584Z
sampled_at__ltestring, (date-time)

Filters for logs sampled at or before this datetime.

Example:sampled_at__lte=2024-04-17T09:39:45.984584Z
expandArray of strings

Specify a url field to expand into a nested resource.

Items Enum:"home_battery""home_battery.model""home_battery.model.make"
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/home_batteries/{home_battery_id}/status_logs?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&sampled_at__gte=2024-04-17T09%3A39%3A45.984584Z&sampled_at__lte=2024-04-17T09%3A39%3A45.984584Z&expand=home_battery' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

List all status logs for a specific home battery, sorted newest first.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default:3600
Bodyapplication/json
Array [
urlstring, (uri)
Example:"https://api.ev.energy/v2/home_batteries/hoba01J5DCXX8DMJDJYGVR1DW4J7AA/status_logs/2024-04-17T09:39:45.984584Z/"
sampled_atstring, (date-time)
home_batteryHomeBattery (object) or string
One of:

A resource that represents a single, physical home battery.

capacity_watt_hoursinteger or null

The total capacity of the battery in Wh.

Example:13500
state_of_charge_percentageinteger or null

Remaining battery charge level as a whole percentage (0-100).

Example:82
charge_rate_wattsinteger or null

Current charge rate in W. A positive value indicates charging.

Example:2200
discharge_limit_percentageinteger or null

Minimum reserve charge level as a whole percentage (0-100).

Example:20
statusstringread-only

Derived operating state of the battery.

Enum:"CHARGING""DISCHARGING""IDLE""FAULT""UNKNOWN"
Example:"CHARGING"
operation_modestringread-only

Current operation mode of the battery.

Enum:"EXPORT_FOCUS""IMPORT_FOCUS""TIME_OF_USE""SELF_RELIANCE""IDLE""UNKNOWN"
Example:"SELF_RELIANCE"
]
Response
[
  {
    "url": "https://api.ev.energy/v2/home_batteries/hoba01J5DCXX8DMJDJYGVR1DW4J7AA/status_logs/2024-04-17T09:39:45.984584Z/",
    "sampled_at": "2019-08-24T14:15:22Z",
    "home_battery": { … },
    "capacity_watt_hours": 13500,
    "state_of_charge_percentage": 82,
    "charge_rate_watts": 2200,
    "discharge_limit_percentage": 20,
    "status": "CHARGING",
    "operation_mode": "SELF_RELIANCE"
  }
]