> ## Documentation Index > Fetch the complete documentation index at: https://docs.nox.energy/llms.txt > Use this file to discover all available pages before exploring further. # Get Devices Battery Typical Charge Discharge Historical > **Preview: not available yet.** This endpoint is documented ahead of its release and currently answers `501 Not Implemented`. Its contract may still change before release. Get the typical charge and discharge of your batteries in kWh for a specific timeframe with 15 min granularity. This is a simulated baseline: how the battery would have behaved in `auto` (pure self-consumption), using the realised pv production and house load. Compare it with the measured charge and discharge to calculate the value of steering. The timestamp refers to the 15 minutes after it. `soc_pct` is the state of charge at the end of that interval. ## OpenAPI ````yaml /api-docs/battery/openapi-battery.json get /v1/devices/battery/typical-charge-discharge/historical openapi: 3.1.0 info: title: NOX Energy API - Battery description: > # Battery API Documentation This documentation shows only the endpoints available to battery users. **Preview:** these endpoints are documented ahead of their release and currently answer `501 Not Implemented`. ## Authentication 1. Get your API key from [NOX Energy](mailto:support@nox.energy). 2. Include the API key in your API calls with the header: `x-api-key: YOUR_API_KEY`. ## Access Level This documentation is specifically for **battery users** who have access to these endpoints. Base URL: [https://api.nox.energy](https://api.nox.energy) version: 1.0.0 servers: - url: https://api.nox.energy description: Production Server security: - ApiKeyAuth: [] tags: - name: Asset Info description: API to get basic information about your assets. - name: Battery Control description: API for battery control specific endpoints. - name: User Management description: API endpoints to manage users and their data. paths: /v1/devices/battery/typical-charge-discharge/historical: get: tags: - Asset Info summary: Get Devices Battery Typical Charge Discharge Historical description: >- **Preview: not available yet.** This endpoint is documented ahead of its release and currently answers `501 Not Implemented`. Its contract may still change before release. Get the typical charge and discharge of your batteries in kWh for a specific timeframe with 15 min granularity. This is a simulated baseline: how the battery would have behaved in `auto` (pure self-consumption), using the realised pv production and house load. Compare it with the measured charge and discharge to calculate the value of steering. The timestamp refers to the 15 minutes after it. `soc_pct` is the state of charge at the end of that interval. operationId: >- get_devices_battery_typical_charge_discharge_historical_v1_devices_battery_typical_charge_discharge_historical_get parameters: - name: start_time in: query required: true schema: type: string description: > Start of the requested period. Intervals starting at or after this time are returned. The time is in UTC in ISO 8601 format. Time format examples: - 2023-10-01T00:00:00Z - 2023-10-01T00:00:00 title: Start Time description: > Start of the requested period. Intervals starting at or after this time are returned. The time is in UTC in ISO 8601 format. Time format examples: - 2023-10-01T00:00:00Z - 2023-10-01T00:00:00 - name: end_time in: query required: true schema: type: string description: > End of the requested period. Intervals starting before this time are returned. The time is in UTC in ISO 8601 format. Time format examples: - 2023-10-01T00:00:00Z - 2023-10-01T00:00:00 title: End Time description: > End of the requested period. Intervals starting before this time are returned. The time is in UTC in ISO 8601 format. Time format examples: - 2023-10-01T00:00:00Z - 2023-10-01T00:00:00 - name: limit in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. default: 1000 title: Limit description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. - name: next_token in: query required: false schema: anyOf: - type: string - type: 'null' description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. title: Next Token description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. - name: aggregated in: query required: false schema: type: boolean description: > If `true`, sum the values of all batteries per interval. If `false`, return the values of each battery separately. **Note**: If `device_id` is given, the aggregated parameter is ignored. default: false title: Aggregated description: > If `true`, sum the values of all batteries per interval. If `false`, return the values of each battery separately. **Note**: If `device_id` is given, the aggregated parameter is ignored. - name: device_id in: query required: false schema: anyOf: - type: string - type: 'null' description: > Battery device ID to get data of. If `None`, all batteries are included. title: Device Id description: > Battery device ID to get data of. If `None`, all batteries are included. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/BatteryEnergyHistoricalResponse' example: data: - measurement_time: 2026-10-16 12:00 device_id: e4da3b7f-bbce-4a45-9d2b-1c0e8f7a6b5c user_id: '1234' charge_kwh: 0.61 discharge_kwh: 0 soc_pct: 58 meta: energy_supplier: Energy Supplier A next_token: >- AYABeH50-To0SRdAWC9BY9aCIaEAAAABAAdhd3Mta21zAE5hcm46YXdzOmttczpldS1jZW50cmFsLTE6ND energy_unit: kWh granularity: 15min output_timezone: UTC '403': description: Your API key has no access to the battery features content: application/json: example: detail: Energy Supplier A is not authorized to access this feature. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '501': description: Not implemented yet content: application/json: example: detail: This endpoint is not available yet. components: schemas: BatteryEnergyHistoricalResponse: properties: data: anyOf: - items: $ref: '#/components/schemas/BatteryEnergyMeasurement' type: array - type: 'null' title: Data description: List of 15 minute values meta: anyOf: - $ref: '#/components/schemas/BatteryEnergyMeta' - type: 'null' description: Response metadata type: object title: BatteryEnergyHistoricalResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BatteryEnergyMeasurement: properties: measurement_time: anyOf: - type: string - type: 'null' title: Measurement Time description: Start of the 15 minute interval the values refer to device_id: anyOf: - type: string - type: 'null' title: Device Id description: Unique device identifier user_id: anyOf: - type: string - type: 'null' title: User Id description: >- Your own identifier of the user, as used internally by you (supplier, OEM or other partner) charge_kwh: anyOf: - type: number - type: 'null' title: Charge Kwh description: Energy charged during the interval in kWh discharge_kwh: anyOf: - type: number - type: 'null' title: Discharge Kwh description: Energy discharged during the interval in kWh soc_pct: anyOf: - type: number - type: 'null' title: Soc Pct description: State of charge in % at the end of the interval type: object title: BatteryEnergyMeasurement BatteryEnergyMeta: properties: energy_supplier: anyOf: - type: string - type: 'null' title: Energy Supplier description: Energy supplier name next_token: anyOf: - type: string - type: 'null' title: Next Token description: Token for pagination energy_unit: anyOf: - type: string - type: 'null' title: Energy Unit description: Unit of the energy values, e.g. kWh granularity: anyOf: - type: string - type: 'null' title: Granularity description: Granularity of the data, e.g. 15min output_timezone: anyOf: - type: string - type: 'null' title: Output Timezone description: Timezone of the output data. type: object title: BatteryEnergyMeta ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: 'API Key authentication. Enter your API key in the format: YOUR_API_KEY' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.