Skip to main content
GET
Battery health (V2)

Overview

Returns battery health scores for the vehicles mapped to your token’s own company. Vehicles of sub-companies are included only if they are also mapped to it. Only vehicles scored on the company’s latest scoring date are returned: a vehicle that was not scored on that date is left out, and if the company has never been scored the response has no items and zero counts. Each item has the vehicle’s score, band, diagnostic badges and component scores, its daily battery voltages for the last 90 days, and its live voltage and engine state. A fleet summary covers every scored vehicle. Supports filtering, searching, sorting and pagination.
The V1 version of this endpoint is Battery health. V2 returns a richer response with scores, bands, 90-day voltage trends, and diagnostic badges instead of ML predictions.
Rate limit: 4 req/s · 30/min · 600/hr · 14,400/day

Endpoint

GET /v2/api/battery-health

Query parameters

integer
default:"1"
Page number, 1 or more. Returned as page.
integer
default:"25"
Items per page. There is no maximum.
string
Optional. Case-insensitive substring match on the vehicle name or the device identifier (the IMEI for Telemax and Flespi devices). % and _ act as wildcards.
integer
default:"0"
Band filter: 0 all; 1 Critical; 2 Fair and Poor; 3 Good and Excellent. Any other value returns all.
integer
default:"0"
Sort field:
  • 0: internal vehicle ID (sortDescending is ignored);
  • 1: vehicle name;
  • 2: score;
  • 3: band, alphabetically (Critical, Excellent, Fair, Good, Poor);
  • 4: daysToReplace;
  • 5: currentVoltage;
  • 6: scoredOn. Every item has the same date, so the order is undefined;
  • 7: badge severity. Ascending (the default) puts the most severe first: DEEP_DISCHARGE, then PARK_DRAIN, TREND_DOWN, CHARGE_DOWN and SHORT_TRIPS, then REPLACE and HEALTHY; ties by score, lowest first. badgeSummary is "" with this sort.
Any other value sorts by internal vehicle ID, like 0. Sorting by internal vehicle ID is the only order without ties: with any other sort (for 7, equal severity and score), items with equal values can repeat or be skipped between pages.
boolean
default:"false"
When true, reverses the sort. Ignored for sortBy 0 and for values outside 0–7.
integer
default:"0"
Only vehicles with this badge: 0 no filter; 1 DEEP_DISCHARGE; 2 ALTERNATOR (never emitted, so it matches nothing); 3 PARK_DRAIN; 4 TREND_DOWN; 5 CHARGE_DOWN; 6 SHORT_TRIPS; 7 REPLACE; 8 HEALTHY. Any other value returns 500.

Response

200 OK — BatteryHealthResponse

Top-level fields

summary

The summary covers every vehicle scored on the latest date. It ignores filter, searchText and badgeFilter.

items[]

Each element in items represents one vehicle.

last90DaysVoltage[]

Daily averages of the external battery voltage over the last 90 days, by UTC date, oldest first. Days without readings are left out, and the array can be empty.

Example response

Error responses

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from POST /v2/api/authentication/token/api-key.

Lifetime: ~24 hours (86,399 seconds). Cache the token and reuse it. Re-authenticate 5 minutes before expiry.

Scoping: API key tokens are scoped by the key's company and its action set; see Token scoping.

No refresh endpoint — re-authenticate with your API key when the token expires.

Query Parameters

pageNumber
integer
default:1

Page number, 1 or more. Returned as page in the response. A lower value returns 500 when the company has scored vehicles (with sortBy 7, the first page instead).

pageSize
integer
default:25

Items per page; no maximum. Returned as pageSize in the response. A negative value returns 500 when the company has scored vehicles (with sortBy 7, no items instead).

searchText
string

Case-insensitive substring match on the vehicle name or the device identifier (the IMEI for Telemax and Flespi devices). % and _ act as wildcards.

filter
integer
default:0

Band filter: 0 = all, 1 = Critical, 2 = Fair and Poor, 3 = Good and Excellent. Any other value returns all.

sortBy
integer
default:0

Sort field: 0 = internal vehicle ID (sortDescending ignored), 1 = vehicle name, 2 = score, 3 = band (alphabetical), 4 = daysToReplace, 5 = currentVoltage, 6 = scoredOn (all equal, order undefined), 7 = badge severity (ascending puts the most severe first; badgeSummary is empty). Any other value sorts by internal vehicle ID, like 0. All other sorts can tie (7 on equal severity and score), and tied items can repeat or be skipped between pages.

sortDescending
boolean
default:false

When true, reverses the sort. Ignored for sortBy 0 and for values outside 0–7.

badgeFilter
integer
default:0

Only vehicles with this badge: 0 = no filter, 1 = DEEP_DISCHARGE, 2 = ALTERNATOR (never emitted), 3 = PARK_DRAIN, 4 = TREND_DOWN, 5 = CHARGE_DOWN, 6 = SHORT_TRIPS, 7 = REPLACE, 8 = HEALTHY. Any other value returns 500 when the company has scored vehicles.

Response

200 OK — A fleet summary and a page of per-vehicle battery health scores, badges, component scores and daily voltages.

summary
object

Counts and average score over every vehicle scored on the latest date; ignores filter, searchText and badgeFilter.

items
object[]

Paginated list of per-vehicle battery health records.

totalCount
integer

Number of vehicles matching filter, searchText and badgeFilter, before pagination.

page
integer

Current page number (1-based).

pageSize
integer

Number of results returned per page.