> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a device > Retrieves a device. ## OpenAPI ````yaml fleet-api/reference/flatpeak-api-spec-fleet.json GET /devices/{device_id} 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}: parameters: - schema: type: string name: device_id in: path required: true description: Flatpeak Device ID. get: tags: - Devices summary: Retrieve a device description: Retrieves a device. operationId: get-device parameters: [] responses: '200': $ref: '#/components/responses/Device' '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: 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' Device: description: Device response. content: application/json: schema: $ref: '#/components/schemas/Device' example: id: dev_63a6087272941ef077a8fd3e object: device live_mode: true device_type: BATTERY_STORAGE oem_id: oem_6a3a8dada72cd0a249ff9528 hardware: hardware_id: PU2426A103557 manufacturer: Nova Systems model_code: PICOXN2 model_name: Pico Ultimate location_id: loc_641b90b758fb8e6293716e40 consent_scopes: - TELEMETRY - CONTROL - LOCATION dispatch_limits: max_import_power_kw: 5 max_export_power_kw: 5 storage_capacity_kwh: 13.5 pv_peak_power_kw: 6.2 response_time: pickup_seconds: 42 apply_seconds: 18 total_seconds: 60 sample_count: 37 telemetry: state_data_delayed: false device_meters_data_delayed: false time_last_seen: '2026-07-08T19:30:00Z' time_created: '2026-01-20T09:30:00Z' schemas: Device: type: object title: Device description: A device connected to your account. properties: id: type: string description: Flatpeak Device ID. example: dev_63a6087272941ef077a8fd3e pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ readOnly: true object: type: string description: Object type, `device`. example: device enum: - device default: device readOnly: true live_mode: type: boolean description: '`true` for live data, `false` for test data.' device_type: type: string enum: - BATTERY_STORAGE - ELECTRIC_VEHICLE - EV_CHARGER - PV_SYSTEM - OTHER readOnly: true description: >- What the device is, as the OEM declares it. A change of type is rejected while the device is enrolled in one of your programs. example: BATTERY_STORAGE oem_id: type: string pattern: ^oem_[A-Za-z0-9]+$ example: oem_6a3a8dada72cd0a249ff9528 description: >- Flatpeak OEM ID: the OEM that connects the device. See [list all OEMs](/fleet-api/reference/oems/list). hardware: $ref: '#/components/schemas/DeviceHardware' location_id: type: string readOnly: true example: loc_641b90b758fb8e6293716e40 pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ description: >- Flatpeak Location ID of the property the device sits behind. Devices at the same property share it; aggregate per location to avoid double counting. The address, coordinates, timezone and currency are on the [location](/fleet-api/reference/locations/retrieve). consent_scopes: type: array readOnly: true items: type: string enum: - TELEMETRY - CONTROL - LOCATION - SETTINGS description: >- Consent scopes the customer has granted you for this device. Grant and revocation times are in [consent history](/fleet-api/reference/devices/consent-history). | Scope | Grants | | :--- | :--- | | `TELEMETRY` | Device state and meter data | | `CONTROL` | Dispatch | | `LOCATION` | Geolocation | | `SETTINGS` | Read and write operating settings | example: - TELEMETRY - CONTROL - LOCATION dispatch_limits: $ref: '#/components/schemas/DispatchLimits' response_time: readOnly: true description: >- How fast the device's OEM fetches and confirms instructions. Derived by Flatpeak. Read only. allOf: - $ref: '#/components/schemas/ResponseTime' telemetry: $ref: '#/components/schemas/Telemetry' time_last_seen: type: string format: date-time description: >- Time when Flatpeak last heard from the device, through its OEM's API calls or telemetry, in UTC. `null` until first contact. example: '2026-03-22T11:12:21Z' nullable: true time_created: type: string description: Time when the object was created, in UTC. example: '2026-01-24T14:15:22Z' format: date-time required: - id - object - live_mode - device_type - oem_id - hardware - location_id - consent_scopes - dispatch_limits - response_time - telemetry - time_last_seen - 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: 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' DeviceHardware: title: DeviceHardware type: object description: Identity of the physical device, as declared by the OEM. additionalProperties: false required: - hardware_id properties: hardware_id: type: string readOnly: true description: >- The device's serial number, or the VIN for vehicles; where neither exists, another unique hardware identifier such as its MAC address, as declared by the OEM. Guarantees one record per physical device. example: PU2426A103557 manufacturer: type: string description: Name of device manufacturer. example: Nova Systems model_code: type: string description: Model code, as declared by the OEM. example: PICOXN2 model_name: type: string description: Model name, as declared by the OEM. example: Pico Ultimate DispatchLimits: title: DispatchLimits type: object description: >- The device's dispatch envelope at the grid connection point, computed by Flatpeak from the OEM's declaration, inverter and connector limits included. Plans are validated against it at submission. additionalProperties: false properties: max_import_power_kw: type: number minimum: 0 description: Maximum power the device can draw from the grid, in kW. example: 8.4 max_export_power_kw: type: number minimum: 0 description: >- Maximum power the device can export to the grid, in kW. 0 when the device cannot export, for example a charge point without V2G. example: 8.4 storage_capacity_kwh: type: number minimum: 0 nullable: true example: 14.2 description: >- Usable energy storage available for dispatch, in kWh. For `EV_CHARGER` devices this is the connected vehicle's capacity. `null` when the device has no storage, when no vehicle is connected, or when the capacity is unknown. pv_peak_power_kw: type: number minimum: 0 nullable: true example: 6.4 description: >- Peak DC generation capacity of the device's solar array, in kWp, as declared by the OEM. `null` when the device has no solar generation. Solar generation cannot be dispatched. It changes the device's expected flows and its export headroom. required: - max_import_power_kw - max_export_power_kw - storage_capacity_kwh - pv_peak_power_kw ResponseTime: type: object title: ResponseTime description: >- Median times, in seconds, over the trailing 30 days for the OEM to fetch instructions and confirm them. `null` when nothing was measured. Use it to set dispatch lead times. additionalProperties: false required: - pickup_seconds - apply_seconds - total_seconds - sample_count properties: pickup_seconds: type: number nullable: true description: >- Median time between an instruction being created and the OEM fetching it, in seconds. example: 42 apply_seconds: type: number nullable: true description: >- Median time between the OEM fetching an instruction and confirming it, in seconds. example: 187 total_seconds: type: number nullable: true description: >- Median time between an instruction being created and its confirmation, in seconds. example: 229 sample_count: type: integer description: >- Number of instructions measured in the trailing window. When `0`, the median fields are `null`. example: 61 Telemetry: title: Telemetry type: object description: Telemetry status. properties: state_data_delayed: type: boolean description: >- `true` when the device's state submissions have stalled beyond the required cadence. example: false device_meters_data_delayed: type: boolean description: >- `true` when the device's own meter records have stalled beyond the required cadence. example: false required: - state_data_delayed - device_meters_data_delayed 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.