> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve device instructions > Returns the VPP operator's instructions for the device within the window, up to 72 hours ahead, as one timeline: VPP event commitments, and plans under a managed tariff. Every segment is binding and names its `vpp_event_id` or `plan_id`. Fetch it when `device.instructions.update` fires for a plan, when `vpp_event.update` reports a locked event, or on your own cadence. Then [confirm](/energy-api/reference/instructions/confirm) what the device will deliver. ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy.json GET /devices/{device_id}/instructions openapi: 3.0.3 info: description: >- The Flatpeak Energy API connects energy hardware (batteries, EV chargers, vehicles, heat pumps, water heaters, solar and generators) to electricity prices, grid fees, and VPP programs. ## Create bearer token Obtain a bearer token from `POST /auth/tokens` using your `account_id` and `secret_key` via basic auth, then send it as `Authorization: Bearer ` on every request. ## Base URL `https://energy-api.flatpeak.com` ## Pagination List endpoints return a `list` envelope with `data`, `next_cursor`, and `url`. Page forward by passing `next_cursor` as `cursor` on the next request, until it is `null`. Cursors are opaque and bound to the endpoint and query parameters that issued them. ## Errors Every non-2xx response uses a standard error envelope with `object`, `type`, `code`, and `message`. Codes are machine-readable and safe to branch on. ## Money Monetary values are decimal numbers and are always paired with a `currency_code` (ISO 4217). Energy is expressed in kilowatt hours (kWh). ## Live vs test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Energy API termsOfService: https://flatpeak.com/legal contact: name: Technical Support email: support@flatpeak.com url: https://flatpeak.com/contact license: name: Apache 2.0 url: https://flatpeak.com/legal servers: - url: https://energy-api.flatpeak.com security: - bearerAuth: [] tags: - name: Authentication description: >- Exchange your account credentials for a bearer token to authenticate API requests. - name: Connect description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection, VPP enrollment, and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). x-tariff-description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). - name: Users description: Create, retrieve, update, delete, and list users. - name: Locations description: Create, retrieve, update, delete, and list locations. - name: Devices description: >- Create, retrieve, update, delete and list devices; submit and retrieve their state; read and write their shared settings. - name: Meters description: Submit meter records and check batch status. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Prices description: Retrieve and audit calculated energy prices. - name: Costs description: Calculate the monetary cost of imported or exported energy. - name: Optimizations description: >- Rank the connected tariff to find the best times to consume or export energy, as inputs to your own scheduling. - name: Dispatch description: >- Fetch the VPP operator's instructions for a device, and confirm what the device will deliver. - name: Events description: Retrieve and list account events. - name: VPP Enrollments description: Create, retrieve and list VPP enrollments, and unenroll a device. - name: VPP Programs description: List VPP programs available to devices. - name: VPP Events description: >- VPP events committed by VPP operators, with your fleet's share and its per-device allocation. You can take over the allocation while it is open. - name: Operator groups description: >- Read-only views of the device groups VPP operators define. You see the groups that touch your fleet, and only your own devices in them. - name: Zones description: >- Network areas VPP operators define that touch your fleet. Read-only. You see only your own devices in them. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /devices/{device_id}/instructions: parameters: - name: device_id in: path required: true schema: type: string example: dev_63a6087272941ef077a8fd3e description: Flatpeak Device ID. get: tags: - Dispatch summary: Retrieve device instructions description: >- Returns the VPP operator's instructions for the device within the window, up to 72 hours ahead, as one timeline: VPP event commitments, and plans under a managed tariff. Every segment is binding and names its `vpp_event_id` or `plan_id`. Fetch it when `device.instructions.update` fires for a plan, when `vpp_event.update` reports a locked event, or on your own cadence. Then [confirm](/energy-api/reference/instructions/confirm) what the device will deliver. operationId: get-device-instructions parameters: - name: end_time in: query required: true schema: type: string example: '2026-06-16T09:00:00Z' format: date-time description: >- RFC 3339 end of the window, for example `2026-06-15T13:00:00Z`. The window starts now and may extend at most 72 hours. responses: '200': $ref: '#/components/responses/Instructions' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: responses: '400': description: >- 400 Bad Request: the request was malformed or a required field is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '401 Unauthorized: authentication credentials are missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '404 Not Found: the requested resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- 422 Unprocessable Entity: the request is well-formed but cannot be processed, for example missing required data. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '429 Too Many Requests: the rate limit has been exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- 500 Internal Server Error: an unexpected error occurred. Safe to retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- 503 Service Unavailable: the service is temporarily down for maintenance. Retry after the indicated delay. content: application/json: schema: $ref: '#/components/schemas/Error' Instructions: description: '200 OK: the device''s instructions.' content: application/json: schema: $ref: '#/components/schemas/Instructions' schemas: Instructions: title: Instructions type: object description: >- The VPP operator's instructions for the device over the window, merged into one timeline: VPP event commitments, and plans under a managed tariff. Where a commitment overlaps a plan, the commitment replaces it for that window. Segments are chronological and never overlap. Each is binding and names its `vpp_event_id` or `plan_id`. `data` is empty when there is nothing to follow. properties: object: type: string example: instructions description: Object type, `instructions`. enum: - instructions live_mode: type: boolean description: '`true` for live data, `false` for test data.' example: true device_id: type: string example: dev_6563a6757360a6d6a628e839 description: Flatpeak Device ID. location_id: type: string example: loc_641b90b758fb8e6293716e40 description: Flatpeak Location ID. timezone: type: string description: Timezone at the location, tz database name such as `Europe/Berlin`. example: Europe/London data: type: array items: $ref: '#/components/schemas/InstructionSegment' description: >- Instruction segments, in chronological order and non-overlapping. Empty when there are none. account_id: type: string example: acc_661677911f2197045e6cf1b1 description: Flatpeak Account ID. time_created: type: string format: date-time example: '2026-01-24T14:15:22Z' description: Time when this object was created, in UTC. required: - object - live_mode - device_id - location_id - timezone - data - account_id - time_created Error: type: object description: Standard error envelope returned by every non-2xx response. required: - object - type - code - message properties: object: type: string enum: - error default: error description: Object type. type: type: string description: High-level error category. example: invalid_request code: type: string description: Machine-readable error code, safe to branch on. example: not_found message: type: string description: Human-readable description of the error. example: The requested resource could not be found. context: type: string description: Optional originating context, for example `api.price_get`. example: api.price_get live_mode: type: boolean description: Whether the error occurred against live or test data. time_created: type: string format: date-time description: Time the error was generated (RFC 3339). example: '2026-01-01T00:00:00Z' InstructionSegment: title: InstructionSegment type: object description: >- One instruction for the device over a window. Every instruction is binding. Power is signed: positive for import, negative for export. properties: start_time: type: string format: date-time description: Segment start, in UTC. example: '2026-08-04T20:14:00Z' end_time: type: string format: date-time description: Segment end, in UTC. example: '2026-08-04T22:00:00Z' power_kw: type: number description: >- Power, in kilowatts. Positive values indicate import, negative values indicate export. example: -4.3 energy_kwh: type: number readOnly: true description: >- Energy the segment implies, in kWh, signed like power: `power_kw` over the segment. Informational, derived by Flatpeak. example: -7.6 vpp_event_id: type: string nullable: true description: >- Flatpeak VPP Event ID the segment is a share of. `null` when the segment comes from a plan. example: vpe_7a1c3e5b9d2f4a6c8e0b1d3f plan_id: type: string nullable: true description: >- Flatpeak Plan ID the segment comes from. `null` when the segment is a VPP event commitment. example: null program_id: type: string description: Flatpeak VPP Program ID the segment runs under. example: vpr_5c8d1f2a7b3e4d6c9a0f1b2c cost: type: object readOnly: true nullable: true description: >- Cost of the segment's energy at the device's tariff, in the device `currency_code`. Computed by Flatpeak from the tariff in force; prices may vary within the segment, cost does not. Negative for export earnings. required: - value - confidence properties: value: type: number description: Monetary value in *large* currency units. example: -1.02 confidence: type: number minimum: 0 maximum: 1 description: >- Estimated confidence of the data: `1` is 100% accurate, `0.1` is 10%. example: 1 required: - start_time - end_time - power_kw - energy_kwh - vpp_event_id - plan_id - program_id - cost securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token obtained from POST /auth/tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.