> ## 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 Forecast 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 planned charge and discharge of your batteries in kWh for a specific timeframe with 15 min granularity, to use in your nominations. This forecast is only available for batteries NOX Energy optimizes: batteries with `dynamic_tariff`, `pv_self_consumption` or `imbalance_optimization` enabled in their settings. It is made every day at a fixed time depending on supplier. The timestamp refers to the 15 minutes after it. `soc_pct` is the planned state of charge at the end of that interval. ## OpenAPI ````yaml /api-docs/battery/openapi-battery.json get /v1/devices/battery/forecast/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/forecast/historical: get: tags: - Asset Info summary: Get Devices Battery Forecast 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 planned charge and discharge of your batteries in kWh for a specific timeframe with 15 min granularity, to use in your nominations. This forecast is only available for batteries NOX Energy optimizes: batteries with `dynamic_tariff`, `pv_self_consumption` or `imbalance_optimization` enabled in their settings. It is made every day at a fixed time depending on supplier. The timestamp refers to the 15 minutes after it. `soc_pct` is the planned state of charge at the end of that interval. operationId: >- get_devices_battery_forecast_historical_v1_devices_battery_forecast_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/BatteryEnergyForecastResponse' example: data: - forecast_time: 2026-10-17 18:00 device_id: e4da3b7f-bbce-4a45-9d2b-1c0e8f7a6b5c user_id: '1234' charge_kwh: 0 discharge_kwh: 1.25 soc_pct: 55 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: BatteryEnergyForecastResponse: properties: data: anyOf: - items: $ref: '#/components/schemas/BatteryEnergyForecast' 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: BatteryEnergyForecastResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BatteryEnergyForecast: properties: forecast_time: anyOf: - type: string - type: 'null' title: Forecast 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: Planned energy charged during the interval in kWh discharge_kwh: anyOf: - type: number - type: 'null' title: Discharge Kwh description: Planned energy discharged during the interval in kWh soc_pct: anyOf: - type: number - type: 'null' title: Soc Pct description: Planned state of charge in % at the end of the interval type: object title: BatteryEnergyForecast 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.