---
title: Reporting API User Guide
description: "Use the TWAICE Reporting API to retrieve KPIs, measurements and system data programmatically: authentication, endpoints, parameters and example responses."
---

[Skip to content](https://support.twaice.com/knowledge/reporting-api-user-guide#main-content)

![TWAICE Help CenterWordmark (2)](https://support.twaice.com/hs-fs/hubfs/Wordmark%20(2).png?width=138&height=28&name=Wordmark%20(2).png)

Open main navigation

Close main navigation

- [Contact us](mailto:support@twaice.com)

[Contact us](mailto:support@twaice.com)

 How can we help you?

- There are no suggestions because the search field is empty.

1. [Help Center](https://support.twaice.com/knowledge?hsLang=en)
2. [Reporting API Guide](https://support.twaice.com/knowledge/reporting-api-guide?hsLang=en)

# Reporting API User Guide

## Learn how to retrieve TWAICE-calculated KPIs through the Reporting API, including its specifications, coverage and authentication.

**On this page**

- [Introduction](https://support.twaice.com/knowledge/reporting-api-user-guide#h_937a1d4a0f)
- [Specifications](https://support.twaice.com/knowledge/reporting-api-user-guide#h_855acc9274)
- [What the Reporting API covers: KPI List](https://support.twaice.com/knowledge/reporting-api-user-guide#h_5d51c8e5ad)
- [Authentication](https://support.twaice.com/knowledge/reporting-api-user-guide#h_bf77ace033)
- [How to Authenticate](https://support.twaice.com/knowledge/reporting-api-user-guide#h_c728615111)
- [Request sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_0470a54c1a)
- [Responses](https://support.twaice.com/knowledge/reporting-api-user-guide#h_afb4715b21)
- [Reporting API Structure](https://support.twaice.com/knowledge/reporting-api-user-guide#h_db5bd80cc5)
- [Authorization](https://support.twaice.com/knowledge/reporting-api-user-guide#h_076da95142)
- [Path Parameters](https://support.twaice.com/knowledge/reporting-api-user-guide#h_2681930376)
- [Query Parameters](https://support.twaice.com/knowledge/reporting-api-user-guide#h_cfea0447f5)
- [System-level KPIs](https://support.twaice.com/knowledge/reporting-api-user-guide#h_9e99415975)
- [Get System Usable and Recoverable Energy](https://support.twaice.com/knowledge/reporting-api-user-guide#h_02d10deb80)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_3e96aded3c)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_237002f12b)
- [Get System Penalty Risk](https://support.twaice.com/knowledge/reporting-api-user-guide#h_34135da7a2)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_ef3aac9b13)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_4ffb8fb3e4)
- [Get System Round-trip Efficiency](https://support.twaice.com/knowledge/reporting-api-user-guide#h_0e6ca2018d)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_8c64fb8449)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_99de79e490)
- [Get System SoH](https://support.twaice.com/knowledge/reporting-api-user-guide#h_4b0b322071)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_496b89e586)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_dca2264869)
- [Get System Throughput](https://support.twaice.com/knowledge/reporting-api-user-guide#h_03c751090e)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_e2c535aa72)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_e834ab7091)
- [String(Rack)-level KPIs](https://support.twaice.com/knowledge/reporting-api-user-guide#h_c5e17c6d4c)
- [Get String SoH](https://support.twaice.com/knowledge/reporting-api-user-guide#h_941ce668b6)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_944641af76)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_a4b9f85aff)
- [Get String Throughput](https://support.twaice.com/knowledge/reporting-api-user-guide#h_7d0bd4883e)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_e2fa015fe7)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_66d10159ea)
- [Get String BMS SoC Error](https://support.twaice.com/knowledge/reporting-api-user-guide#h_ed1dff6d8e)
- [Endpoint](https://support.twaice.com/knowledge/reporting-api-user-guide#h_879df1d518)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_e6b8375f26)
- [Validation Errors](https://support.twaice.com/knowledge/reporting-api-user-guide#h_b66ef3ddfc)
- [Response sample](https://support.twaice.com/knowledge/reporting-api-user-guide#h_98282a03cb)

### Introduction

The **TWAICE Reporting API** is a standard REST API interface that allows customers to retrieve TWAICE-calculated KPIs using secure, programmatic queries - enabling access to TWAICE battery performance, health, and operational insights into external reporting, BI, and analytics environments.

This document guides you through how to access and use the TWAICE Reporting API.

### Specifications

- The TWAICE Reporting API follows REST architecture principles.
- All API requests must be made over HTTPS.
- The API returns responses in JSON format.
- Authentication is token-based using JWT.
- Supported date format is ISO 8601.
- Reporting endpoints provide access to **only** **TWAICE-calculated KPIs** - following the definitions described in [Guide to TWAICE KPIs](https://support.twaice.com/knowledge/guide-to-twaice-kpis?hsLang=en) article.
- Raw sensor data is not accessible.
- Data is available at **daily aggregation level** and only on **system and string level KPIs** (SoH is updated weekly).
- Historical data access is limited to **last 30 days.**
- **Rate limits:** The API allows up to 1,000 requests per day, with a burst limit of 100 requests per 5 minutes. If these limits are exceeded, requests are throttled and return HTTP 429 (Too Many Requests).

### What the Reporting API covers: KPI List

| **Level** | **KPI** |
| --- | --- |
| System | Usable & Recoverable Energy |
| System | Penalty Risk (SoC limits) |
| System | Round-trip Efficiency |
| System | State of Health |
| System | Throughput (charge/discharge energy and cycle counts) |
| String/Rack | State of Health |
| String/Rack | Throughput (charge/discharge energy and cycle counts) |
| String/Rack | BMS SoC Error |

 

### Authentication

- Authentication is done via JWT Tokens as the TWAICE API authorization key.
- To obtain a token, use the authentication endpoint with your `email` and `password`.
- Tokens are available only for registered users with valid credentials.
- Once obtained, the token must be included as a Bearer token in the request header.

- Token validity is **60 minutes**.

 

```
Authorization: Bearer JWT_TOKEN
```

 

### How to Authenticate

Authenticate the user to obtain a token for API requests.

| email (required) | string |
| --- | --- |
| password (required) | string |

 

⚠️ To access the Reporting API, we need to update your user role permissions first. Please reach out to your TWAICE support contact!

### Request sample

`POST /auth/authenticate`

API endpoint: [https://api.twaice.ai/auth/authenticate](https://api.twaice.ai/auth/authenticate)

US: [https://api.us.twaice.ai/auth/authenticate](https://api.twaice.ai/auth/authenticate)

Australia: [https://api.ap.twaice.ai/auth/authenticate](https://api.twaice.ai/auth/authenticate)<https://api.twaice.ai/auth/authenticate>

**Payload**

Content type: application/json

```
{  "email": "johnDoe123@gmail.com",  "password": "d4f089b1e7a6"}
```

 

### Responses

**HTTP 201 "Created": Login with provided credentials is successful**

Response Schema: `application/json`

| idToken | string Cognito Token used for API Gateway Auth and Ingest Auth |
| --- | --- |

 

**Response Sample:**

```
{  "idToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZGYy"}
```

 

**HTTP 400 "Bad Request":** **Validation Error for the request input**

Response Body Schema: `application/json`

| status (required) | string Enum: "success", "error" |
| --- | --- |
| data (required) | object |
| message (required) | string Error message if status is error |

 

**Response Sample:**

```
{  "status": "error",  "data": {    "statusCode": 400,    "message": [      "email should not be empty"    ],    "error": "Bad Request"  },  "message": "Bad Request Exception"}
```

 

**HTTP 401 "Unauthorized": Invalid login credentials**

Response Body Schema: `application/json`

| status (required) | string Enum: "success", "error" |
| --- | --- |
| data (required) | object |
| message (required) | string Error message if status is error |

 

**Response Sample:**

```
{  "status": "error",  "data": {    "statusCode": 401,    "message": "Incorrect username or password.",    "error": "Unauthorized"  },  "message": "Incorrect username or password."}
```

 

### Reporting API Structure

The Reporting API provides access to KPI data via structured endpoints.

All endpoints follow this structure:

```
/data-explorer/{customer_bk}/{system_bk}/reporting_kpi/{scope}/{kpi}
```

 

Where:

- `{scope}` = `system` or `string`
- `{kpi}` = specific KPI (e.g. `soh`, `throughput`, `rte`)

### Authorization

All requests require:

```
Authorization: Bearer JWT_TOKEN
```

 

### Path Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| customer\_bk | string | yes | Business key of the customer |
| system\_bk | string | yes | Business key of the system |

 

### Query Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| start\_timestamp | string (date-time) | no | Start of time range |
| end\_timestamp | string (date-time) | no | End of time range |

 

### System-level KPIs

Endpoints that provide KPIs aggregated at system level.

### Get System Usable and Recoverable Energy

Returns system-level usable energy (available energy) and energy loss breakdown.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/system/usable_energy
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "my-system",      "component_name": "My system",      "energy_loss_aging_wh": 50000,      "total_available_energy_wh": 1200000,      "missing_data_energy_wh": 10000,      "recoverable_energy_wh": 20000    }  ]}
```

 

### Get System Penalty Risk

Returns system-level penalty risk and recommended operating SoC limits.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/system/penalty_risk
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "my-system",      "component_name": "My system",      "soc_recommended_lower_limit_pct": 10,      "soc_recommended_upper_limit_pct": 90,      "dischargeable_energy_lower_limit_wh": 100000,      "dischargeable_energy_upper_limit_wh": 900000    }  ]}
```

 

### Get System Round-trip Efficiency

Returns system round-trip efficiency.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/system/rte
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "my-system",      "component_name": "My system",      "system_round_trip_efficiency_pct": 92.5    }  ]}
```

 

### Get System SoH

Returns system-level State of Health KPIs.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/system/soh
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "my-system",      "component_name": "My system",      "soh_pct": 95.2,      "soh_energy_wh": 120000    }  ]}
```

 

### Get System Throughput

Returns system-level charge, discharge, energy, and cycle metrics.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/system/throughput
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "my-system",      "component_name": "My system",      "capacity_discharge_daily_ah": 1200,      "capacity_charge_daily_ah": 1250,      "capacity_absolute_daily_ah": 2450,      "capacity_net_daily_ah": 50,      "energy_discharge_daily_wh": 480000,      "energy_charge_daily_wh": 500000,      "energy_absolute_daily_wh": 980000,      "energy_net_daily_wh": 20000,      "capacity_charge_cycles_daily": 0.8,      "capacity_discharge_cycles_daily": 0.75,      "capacity_cycles_daily": 0.78,      "energy_charge_cycles_daily": 0.82,      "energy_discharge_cycles_daily": 0.79,      "energy_cycles_daily": 0.81,      "capacity_discharge_ah": 350000,      "capacity_charge_ah": 360000,      "capacity_absolute_ah": 710000,      "capacity_net_ah": 10000,      "energy_discharge_wh": 140000000,      "energy_charge_wh": 145000000,      "energy_absolute_wh": 285000000,      "energy_net_wh": 5000000,      "capacity_charge_cycles": 320,      "capacity_discharge_cycles": 315,      "capacity_cycles": 318,      "energy_charge_cycles": 325,      "energy_discharge_cycles": 320,      "energy_cycles": 323    }  ]}
```

 

### String(Rack)-level KPIs

Endpoints that provide KPIs at string(rack) level.

### Get String SoH

Returns string-level State of Health with confidence interval.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/string/soh
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "string-1",      "component_name": "String 1",      "soh_pct": 96.1,      "soh_confidence_lower_bound_pct": 94.5,      "soh_confidence_upper_bound_pct": 97.5    }  ]}
```

 

### Get String Throughput

Returns string-level charge, discharge, and cycle metrics.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/string/throughput
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "string-1",      "component_name": "String 1",      "capacity_absolute_ah": 71000,      "capacity_charge_ah": 36000,      "capacity_discharge_ah": 35000,      "capacity_net_ah": 1000,      "energy_absolute_wh": 28500000,      "energy_charge_wh": 14500000,      "energy_discharge_wh": 14000000,      "energy_net_wh": 500000,      "capacity_charge_cycles": 320,      "capacity_discharge_cycles": 315,      "capacity_cycles": 318,      "energy_charge_cycles": 325,      "energy_discharge_cycles": 320,      "energy_cycles": 323    }  ]}
```

 

### Get String BMS SoC Error

Returns string-level SoC charge and discharge accuracy by comparing the `bms_string_soc` with the OCV. If `bms_string_soc` is far off from the OCV, error is higher.

### Endpoint

```
GET /data-explorer/{customer_bk}/{system_bk}/reporting_kpi/string/bms_soc_error
```

 

### Response sample

```
{  "items": [    {      "event_timestamp": "2024-01-01T00:00:00Z",      "component_id": "string-1",      "component_name": "String 1",      "bms_soc_safety_margin_charge_pct": 98.5,      "bms_soc_safety_margin_discharge_pct": 97.8    }  ]}
```

 

### Validation Errors

All Reporting API endpoints may return a validation error if required path parameters or query parameters are invalid.

**HTTP 422: Validation Error**

Response Body Schema: `application/json`

| type | string Default: "about:blank" A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type. |
| --- | --- |
| title | string A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized. |
| status | integer \[100 .. 600) Default: 500 The HTTP status code generated by the origin server for this occurrence of the problem. |
| detail | string A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized. |
| instance | string A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code. |
| timestamp | number \[946684800 .. 4102444800\] Unix timestamp in seconds with optional Microseconds as fraction. The unix timestamp is the number of seconds between a particular date and the Unix Epoch on January 1st, 1970 at UTC. Must be after 2000-01-01 00:00:00 GMT+0000 Must be before 2100-01-01 00:00:00 GMT+0000 Example: 1642770062.123456 == 2022-01-21T14:01:02.123456Z, with the fraction representing 123.456 milliseconds or 123456 microseconds respectively |
| errors | array of objects A list of error objects with detailed information about each of the subproblem, which occurred in API call. |

### Response sample

```
{  "type": "https://docs.twaice.ai/#section/422:-Unprocessable-Entity",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Request contains invalid data, more information about the specific problem could be found in errors field",  "instance": "/system/11223344/sensor/55667788",  "timestamp": 1642770062.123456,  "errors": [    {      "title": "value_error.missing",      "detail": "field required",      "instance": "/body/timestamp"    }  ]}
```

 

### Response sample

© 2026 TWAICE Technologies GmbH

[twaice.com](https://www.twaice.com)      [Privacy](https://www.twaice.com/legal/data-protection-notice)      [Imprint](https://www.twaice.com/legal/legal-notice)