> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # List all VPP events > Returns the VPP events that draw on your fleet, most recent first, each with your fleet's committed `power_kw` and the per-device allocation. ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy.json GET /vpp-events 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: /vpp-events: parameters: [] get: tags: - VPP Events summary: List all VPP events description: >- Returns the VPP events that draw on your fleet, most recent first, each with your fleet's committed `power_kw` and the per-device allocation. operationId: list-all-vpp-events parameters: - schema: type: string enum: - ALLOCATION_OPEN - LOCKED - ACTIVE - COMPLETE - CANCELED name: status in: query required: false description: Only events in this status. - schema: type: string enum: - ECONOMIC - TEST name: event_type in: query required: false description: Only events of this type. - schema: type: string name: group_id in: query required: false description: Only events created for this group. - schema: type: string format: date-time name: start_time in: query required: false description: Only events whose window overlaps the range starting here, in UTC. - schema: type: string format: date-time name: end_time in: query required: false description: Only events whose window overlaps the range ending here, in UTC. - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' responses: '200': $ref: '#/components/responses/VppEventList' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: parameters: limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 30 description: Maximum number of objects to return per page, default 30. Maximum 100. cursor: name: cursor in: query required: false schema: type: string description: >- Pagination cursor. Pass `next_cursor` from the previous response unchanged; omit for the first page. A cursor used with different parameters returns `400 cursor_invalid`. responses: '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' '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' VppEventList: description: VPP event list response. content: application/json: schema: allOf: - $ref: '#/components/schemas/ListResponse' - type: object properties: data: type: array description: The page of results. items: $ref: '#/components/schemas/VppEvent' schemas: ListResponse: type: object description: Standard envelope for paginated list endpoints. required: - object - url - next_cursor - data properties: object: type: string enum: - list default: list description: Object type. url: type: string description: URL for this list. example: /users next_cursor: type: string nullable: true description: >- Opaque cursor for the next page. Pass it as `cursor` on the next request. `null` on the last page. Do not stop on a short or empty `data` array. example: djF8ZXZ0fGE5ZjN8NjYxNjc3ODdjMTY1MmIzZmJlYmE1ZjAx data: type: array items: {} description: The page of results. VppEvent: title: VppEvent type: object description: >- A VPP event as it applies to your fleet: the VPP operator's committed power per interval and the allocation of your devices' shares. Flatpeak allocates the shares. At lock, each share becomes a commitment in the device's instructions. properties: id: type: string description: Flatpeak VPP Event ID. example: vpe_7d2a4c6e9b1f3a5c8e0d2f4b object: type: string example: vpp_event description: Object type, `vpp_event`. enum: - vpp_event live_mode: type: boolean description: '`true` for objects created in live mode.' example: true operator_id: type: string description: Flatpeak ID of the VPP operator. example: opr_6a3548352c0d07e89d47b7f1 event_type: type: string readOnly: true enum: - ECONOMIC - TEST description: >- `ECONOMIC`: market-driven, the default. `TEST`: exercises the dispatch chain without settlement. example: ECONOMIC start_time: type: string format: date-time description: 'Event envelope start: the first interval''s start, in UTC. Read only.' example: '2026-08-25T18:00:00Z' readOnly: true end_time: type: string format: date-time description: 'Event envelope end: the last interval''s end, in UTC. Read only.' example: '2026-08-25T20:00:00Z' readOnly: true intervals: type: array minItems: 1 description: >- The shape of the event as it applies to your fleet: one or more ordered, non-overlapping intervals, each carrying your fleet's committed share for that interval, signed: positive import, negative export. items: type: object properties: start_time: type: string format: date-time description: Interval start, in UTC. example: '2026-08-04T20:14:00Z' end_time: type: string format: date-time description: Interval end, in UTC. example: '2026-08-04T21:00:00Z' power_kw: type: number description: >- Your fleet's committed share over this interval, in kilowatts, signed: positive import, negative export. example: -11 energy_kwh: type: number readOnly: true description: >- Energy your fleet's share implies over the interval, in kWh, signed like power. Informational, derived by Flatpeak. example: -8.4 cost: type: object readOnly: true nullable: true description: >- Cost of your fleet's share over the interval, at each device's tariff, in the device currency. Computed by Flatpeak from tariffs; prices vary within the interval, cost does not. Negative for export earnings. required: - value - confidence properties: value: type: number description: Monetary value in *large* currency units. example: 2.15 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 - cost - energy_kwh group_id: type: string readOnly: true description: >- Flatpeak Group ID: the VPP operator's group the event was created for. Your devices that were in the group at that moment are in the event. Read it with [retrieve a group](/energy-api/reference/groups/retrieve). example: grp_2f6a9c1d8e3b5a7c4d0e9f1a status: type: string enum: - ALLOCATION_OPEN - LOCKED - ACTIVE - COMPLETE - CANCELED description: >- | Value | Meaning | | :--- | :--- | | `ALLOCATION_OPEN` | Until `time_allocation_locks`. Device shares can still change | | `LOCKED` | Shares fixed. `vpp_event.update` fires once for the event; read every device's share from `allocation` | | `ACTIVE` | During the window | | `COMPLETE` | After the window | | `CANCELED` | Withdrawn by the VPP operator | example: ALLOCATION_OPEN time_allocation_locks: type: string format: date-time description: >- Time after which the allocation is fixed, in UTC. Until then Flatpeak may rebalance shares. example: '2026-08-25T16:00:00Z' allocation: type: array readOnly: true description: >- The current allocation per device and window. Rows tile the event's intervals; a device with no row for a window was given no share for it. items: type: object properties: device_id: type: string description: Flatpeak Device ID. example: dev_63a6087272941ef077a8fd3e program_id: type: string readOnly: true description: >- The program this device participates under: the program of its `ACTIVE` enrollment. Terms such as opt-out policy, rewards and penalties follow it. example: vpr_6a1f8e375db9de605baadd46 start_time: type: string format: date-time description: Start of the window this row allocates, in UTC. example: '2026-08-25T18:00:00Z' end_time: type: string format: date-time description: >- End of the window this row allocates, in UTC. Together with `start_time` the row is self-contained; windows lie within a single event interval and normally coincide with it. example: '2026-08-25T19:00:00Z' power_kw: type: number description: >- The device's share over the interval, signed: positive import, negative export. example: -4.3 energy_kwh: type: number readOnly: true description: >- Energy the row implies, in kWh, signed like power: `power_kw` over the window. Informational, derived by Flatpeak. example: -3.3 cost: type: object readOnly: true nullable: true description: >- Cost of the row's energy at the device's tariff, in the device `currency_code`. Computed by Flatpeak. Negative for export earnings. required: - value - confidence properties: value: type: number description: Monetary value in *large* currency units. example: -0.94 confidence: type: number minimum: 0 maximum: 1 description: >- Estimated confidence of the data: `1` is 100% accurate, `0.1` is 10%. example: 1 required: - device_id - start_time - power_kw - end_time - program_id - cost - energy_kwh device_count: type: integer readOnly: true description: >- Your devices in the event: those that were in the VPP operator's group when the event was created. example: 61 time_updated: type: string format: date-time description: Time when the event was created or last updated, in UTC. example: '2026-08-25T14:00:12Z' time_created: type: string format: date-time description: Time when the event was created, in UTC. example: '2026-08-25T14:00:12Z' account_id: type: string example: acc_661677911f2197045e6cf1b1 description: Flatpeak Account ID. required: - id - object - live_mode - operator_id - start_time - end_time - status - time_allocation_locks - allocation - time_created - account_id - intervals - group_id x-examples: Example 1: id: vpe_7d2a4c6e9b1f3a5c8e0d2f4b object: vpp_event live_mode: true operator_id: opr_6a3548352c0d07e89d47b7f1 event_type: ECONOMIC start_time: '2026-08-25T18:00:00Z' end_time: '2026-08-25T20:00:00Z' intervals: - start_time: '2026-08-25T18:00:00Z' end_time: '2026-08-25T19:00:00Z' power_kw: -11 - start_time: '2026-08-25T19:00:00Z' end_time: '2026-08-25T20:00:00Z' power_kw: -7.5 group_id: grp_2f6a9c1d8e3b5a7c4d0e9f1a status: ALLOCATION_OPEN time_allocation_locks: '2026-08-25T16:00:00Z' allocation: - device_id: dev_63a6087272941ef077a8fd3e program_id: vpr_6a1f8e375db9de605baadd46 start_time: '2026-08-25T18:00:00Z' end_time: '2026-08-25T19:00:00Z' power_kw: -4.3 - device_id: dev_63a6087272941ef077a8fd3e program_id: vpr_6a1f8e375db9de605baadd46 start_time: '2026-08-25T19:00:00Z' end_time: '2026-08-25T20:00:00Z' power_kw: -3.2 - device_id: dev_63a6087272941ef077a8fd55 program_id: vpr_8e1b3d5f7a9c2e4b6d8f0a2c start_time: '2026-08-25T18:00:00Z' end_time: '2026-08-25T19:00:00Z' power_kw: -3.8 device_count: 61 time_updated: '2026-08-25T14:00:12Z' time_created: '2026-08-25T14:00:12Z' account_id: acc_661677911f2197045e6cf1b1 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' 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.