> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a dispatch timeline > Returns the device's net energy flows over the window, past or future, up to 90 days. Intervals are contiguous and each carries its `origin`, `energy_source`, instruction timestamps and `confidence` (1 where metered). ## OpenAPI ````yaml fleet-api/reference/flatpeak-api-spec-fleet.json GET /devices/{device_id}/timeline openapi: 3.0.3 info: description: >- The Flatpeak Fleet API. VPP operators use it to enroll, dispatch and settle OEM device fleets. ## Authentication Exchange your `account_id` and `secret_key` for a bearer token at `POST /auth/tokens` with basic auth. Send it as `Authorization: Bearer ` on every request. ## Base URL `https://fleet-api.flatpeak.com` ## Pagination Lists return `data`, `next_cursor` and `url`. Pass `next_cursor` as `cursor` until it is `null`. A cursor is opaque and bound to the endpoint and query parameters that issued it. ## Errors Every non-2xx response carries `object`, `type`, `code` and `message`. Branch on `code`. ## Money and energy Money is a decimal number paired with a `currency_code` (ISO 4217). Power is in kW and energy in kWh. Positive is import, negative is export. ## Live and test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Fleet 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://fleet-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 for onboarding customers through your own app. - name: OEMs description: List and retrieve the OEMs whose devices your fleet can reach. - name: Devices description: >- Retrieve, list and update the devices connected to your account, and read their consent history and shared settings. - name: Locations description: >- Read the location a device sits behind: its timezone, currency, metering and your devices there. - name: Dispatch description: Submit plans to devices on managed tariffs and read the dispatch timeline. - name: Telemetry description: Read device state, device meter records and location meter records. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Events description: Retrieve and list account events. - name: VPP Programs description: >- Define and manage VPP programs: the commercial terms devices enroll under, and their live state. - name: Groups description: >- Named collections of devices for bulk dispatch and aggregated reads. OEMs see them read-only as [groups](/energy-api/reference/groups/list) on the Energy API. - name: Zones description: >- Network areas resolved to devices by Flatpeak, for locational eligibility and grouping without handling addresses. - name: Exports description: >- Package settlement evidence, consent records and enrollment registers as downloadable files. - name: Rewards description: >- The reward ledger: entries accrue from delivery, you approve them, pay the customers and mark them paid. - name: VPP Enrollments description: Track and act on device enrollments across your programs. - name: VPP Events description: >- Commit market activations: create an event for a group, then read its state and its devices' results. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /devices/{device_id}/timeline: parameters: - schema: type: string name: device_id in: path required: true description: Flatpeak Device ID. get: tags: - Dispatch summary: Retrieve a dispatch timeline description: >- Returns the device's net energy flows over the window, past or future, up to 90 days. Intervals are contiguous and each carries its `origin`, `energy_source`, instruction timestamps and `confidence` (1 where metered). operationId: get-dispatch-timeline parameters: - name: start_time in: query required: true schema: type: string format: date-time example: '2026-07-12T18:00:00Z' description: Start of the window, in UTC. May be in the past. - name: end_time in: query required: true schema: type: string format: date-time example: '2026-07-14T18:00:00Z' description: End of the window, in UTC. At most 90 days after `start_time`. - name: aggregate_by in: query required: false schema: type: string enum: - NON_FIXED - HALF_HOUR - HOUR - DAY example: NON_FIXED description: >- Aggregation period: `NON_FIXED` (default, native resolution), `HALF_HOUR`, `HOUR` or `DAY`. responses: '200': $ref: '#/components/responses/DispatchTimeline' '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' DispatchTimeline: description: Dispatch timeline response. content: application/json: schema: $ref: '#/components/schemas/DispatchTimeline' example: object: dispatch_timeline device_id: dev_63a6087272941ef077a8fd3e live_mode: true timezone: America/Los_Angeles data: - time_created: null time_fetched: '2026-08-04T19:31:08Z' time_confirmed: '2026-08-04T19:31:40Z' origin: OPERATOR energy_source: BATTERY start_time: '2026-08-04T20:00:00Z' end_time: '2026-08-04T20:30:00Z' energy_kwh: -2.15 confidence: 1 - time_created: null time_fetched: '2026-08-04T19:31:08Z' time_confirmed: '2026-08-04T19:31:40Z' origin: OPERATOR energy_source: BATTERY start_time: '2026-08-04T20:30:00Z' end_time: '2026-08-04T21:00:00Z' energy_kwh: -2.15 confidence: 1 - time_created: null time_fetched: null time_confirmed: null origin: OEM energy_source: GRID start_time: '2026-08-04T21:00:00Z' end_time: '2026-08-04T21:30:00Z' energy_kwh: 1.2 confidence: 0.8 oem_id: oem_6a3a8dada72cd0a249ff9528 schemas: DispatchTimeline: title: DispatchTimeline type: object description: >- Net flows at the device connection point over the window. Future intervals are forecast from instructions, confirmations and telemetry; past ones derive from meter records, `confidence` 1 where metered. Intervals are contiguous. properties: object: type: string example: dispatch_timeline description: Object type, `dispatch_timeline`. enum: - dispatch_timeline device_id: type: string description: Flatpeak Device ID. example: dev_63a6087272941ef077a8fd3e live_mode: type: boolean description: '`true` for live data, `false` for test data.' timezone: type: string example: Europe/London description: IANA timezone at the device's location. data: type: array description: Contiguous forecast intervals covering the full window. items: $ref: '#/components/schemas/DispatchTimelineInterval' oem_id: type: string pattern: ^oem_[A-Za-z0-9]+$ example: oem_6a3a8dada72cd0a249ff9528 description: 'Flatpeak OEM ID: the OEM that connects the device.' required: - object - device_id - live_mode - timezone - data - oem_id 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: access_denied 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' DispatchTimelineInterval: title: DispatchTimelineInterval type: object description: >- One interval of the dispatch timeline: when its instruction was submitted, fetched and confirmed, what shaped it and whether delivery is metered. properties: time_created: type: string description: >- Time the plan shaping the interval was submitted, in UTC. `null` when no plan covers the interval. format: date-time example: '2026-07-13T09:12:04Z' nullable: true time_fetched: type: string description: >- Time the OEM fetched the instruction shaping the interval, in UTC. `null` for `OEM` intervals. format: date-time example: '2026-07-13T09:13:01Z' nullable: true time_confirmed: type: string description: >- Time the OEM confirmed the instruction shaping the interval, in UTC. `null` for `OEM` intervals. format: date-time example: '2026-07-13T16:02:11Z' nullable: true origin: type: string enum: - OPERATOR - OEM description: |- Who shaped the interval. | Value | Meaning | | :--- | :--- | | `OPERATOR` | A VPP event commitment or your plan. Binding | | `OEM` | The OEM's own operation of the device | example: OPERATOR energy_source: type: string example: BATTERY description: 'Source of the energy: `GRID`, `BATTERY` or `PV`.' enum: - GRID - PV - BATTERY start_time: type: string format: date-time example: '2026-07-13T19:00:00Z' description: Time when this interval starts, in UTC. end_time: type: string format: date-time example: '2026-07-13T19:30:00Z' description: Time when this interval ends, in UTC. energy_kwh: type: number example: -1.9 description: >- Net energy expected over the interval, in kWh. Positive is import, negative is export. confidence: type: number minimum: 0 maximum: 1 example: 0.8 description: >- Confidence in the data, from 0 to 1, where 1 is fully accurate. It falls further into the forecast window and while the device has little telemetry history. required: - time_created - time_fetched - time_confirmed - origin - energy_source - start_time - end_time - energy_kwh - confidence securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authenticate with the `bearer_token` obtained from the [authentication](/fleet-api/reference/authentication) endpoint. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.