Battery health - Telemax Docs

Battery health (V2)

curl --request GET \
  --url https://api.telemax.com.au/api/v2/battery-health \
  --header 'Authorization: Bearer <token>'

{
  "summary": {
    "healthyCount": 0,
    "warningCount": 1,
    "criticalCount": 1,
    "avgScore": 58.5
  },
  "items": [
    {
      "vehicleId": 24381,
      "vehicleName": "Teltonika Test Device A",
      "imei": "865124071644076",
      "currentVoltage": 12.31,
      "isEngineOn": false,
      "voltageHistory": {
        "7day": {
          "peak": 12.31,
          "average": 12.25,
          "lowest": 11.92
        },
        "30day": {
          "peak": 12.72,
          "average": 11.47,
          "lowest": 2.11
        },
        "60day": {
          "peak": 12.72,
          "average": 11.62,
          "lowest": 2.11
        },
        "90day": {
          "peak": 12.72,
          "average": 11.62,
          "lowest": 2.11
        }
      },
      "forecast": {
        "score": 41,
        "comment": "AI analysis predicts optimal performance for the next 90+ days."
      },
      "statuses": [
        {
          "id": "HEALTHY",
          "label": "Healthy",
          "comment": "All signals within normal range.",
          "signalPattern": "No other badges firing"
        }
      ],
      "healthScore": {
        "score": 41,
        "maxScore": 100,
        "comment": "All signals within normal range.",
        "composition": {
          "restingVoltage": "Bad",
          "crankVoltage": "Bad",
          "trend": "Fair",
          "decay": "Fair",
          "chargeAcceptance": "Fair",
          "latestReading": "Fair"
        }
      },
      "last90DaysVoltage": [
        {
          "date": "2026-03-27",
          "voltage": 12.31
        },
        {
          "date": "2026-03-28",
          "voltage": 12.31
        }
      ],
      "band": "Critical",
      "restScore": 10,
      "crankScore": 8,
      "trendScore": 6,
      "decayScore": 7,
      "chargeScore": 5,
      "latestScore": 5,
      "daysToReplace": 90,
      "scoredOn": "2026-05-27",
      "badges": [
        "HEALTHY"
      ]
    }
  ],
  "totalCount": 2,
  "page": 1,
  "pageSize": 25
}

GET

api

battery-health

Battery health (V2)

curl --request GET \
  --url https://api.telemax.com.au/api/v2/battery-health \
  --header 'Authorization: Bearer <token>'

{
  "summary": {
    "healthyCount": 0,
    "warningCount": 1,
    "criticalCount": 1,
    "avgScore": 58.5
  },
  "items": [
    {
      "vehicleId": 24381,
      "vehicleName": "Teltonika Test Device A",
      "imei": "865124071644076",
      "currentVoltage": 12.31,
      "isEngineOn": false,
      "voltageHistory": {
        "7day": {
          "peak": 12.31,
          "average": 12.25,
          "lowest": 11.92
        },
        "30day": {
          "peak": 12.72,
          "average": 11.47,
          "lowest": 2.11
        },
        "60day": {
          "peak": 12.72,
          "average": 11.62,
          "lowest": 2.11
        },
        "90day": {
          "peak": 12.72,
          "average": 11.62,
          "lowest": 2.11
        }
      },
      "forecast": {
        "score": 41,
        "comment": "AI analysis predicts optimal performance for the next 90+ days."
      },
      "statuses": [
        {
          "id": "HEALTHY",
          "label": "Healthy",
          "comment": "All signals within normal range.",
          "signalPattern": "No other badges firing"
        }
      ],
      "healthScore": {
        "score": 41,
        "maxScore": 100,
        "comment": "All signals within normal range.",
        "composition": {
          "restingVoltage": "Bad",
          "crankVoltage": "Bad",
          "trend": "Fair",
          "decay": "Fair",
          "chargeAcceptance": "Fair",
          "latestReading": "Fair"
        }
      },
      "last90DaysVoltage": [
        {
          "date": "2026-03-27",
          "voltage": 12.31
        },
        {
          "date": "2026-03-28",
          "voltage": 12.31
        }
      ],
      "band": "Critical",
      "restScore": 10,
      "crankScore": 8,
      "trendScore": 6,
      "decayScore": 7,
      "chargeScore": 5,
      "latestScore": 5,
      "daysToReplace": 90,
      "scoredOn": "2026-05-27",
      "badges": [
        "HEALTHY"
      ]
    }
  ],
  "totalCount": 2,
  "page": 1,
  "pageSize": 25
}

Overview

Battery health is available for select customers only.

Returns battery health data for all vehicles in the caller’s company. Includes a fleet-level summary and per-vehicle scores, voltage history, diagnostic badges, and component scores. 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: 30 requests per 60 seconds per token.

Endpoint

GET /api/v2/battery-health

Query parameters

pageNumber

integer

default:"1"

Page number (1-based).

pageSize

integer

default:"25"

Number of results per page.

searchText

string

Optional filter by vehicle name.

filter

integer

default:"0"

Band filter: 0 = All, 1 = Critical, 2 = Warning, 3 = Healthy.

sortBy

integer

default:"0"

Sort field (maps to BatteryHealthSortField enum values).

sortDescending

boolean

default:"false"

When true, sort results in descending order.

badgeFilter

integer

default:"0"

Badge filter (maps to BatteryHealthBadge enum values; 0 = None / no filter).

Response

200 OK — BatteryHealthResponse

Top-level fields

Field	Type	Description
currentVoltage	number \| null	Latest observed battery voltage (V)
isEngineOn	boolean \| null	Whether the engine is currently running
voltageHistory	object	Peak, average, and lowest voltage over rolling windows — see below
forecast	object	Short-term battery forecast — see below
statuses	array	Active diagnostic statuses — see below
healthScore	object	Overall health score and component breakdown — see below

`voltageHistory`

Contains four rolling-window objects keyed 7day, 30day, 60day, and 90day. Each has the same shape:

Field	Type	Description
peak	number	Highest voltage observed in the window (V)
average	number	Mean voltage in the window (V)
lowest	number	Lowest voltage observed in the window (V)

`forecast`

Field	Type	Description
score	string	Forecast score label (e.g. `"90+"`)
comment	string	Human-readable forecast summary

`statuses[]`

Field	Type	Description
id	integer	Status identifier
label	string	Short diagnostic label (e.g. `"Park Drain"`)
comment	string	Human-readable description of the condition
signalPattern	string	Signal rule that triggered this status

`healthScore`

Field	Type	Description
score	integer	Overall health score (0–100)
maxScore	integer	Maximum possible score
comment	string	Human-readable summary of the score and recommended action
composition	object	Per-component ratings — see below

`healthScore.composition`

Field	Type	Description
restingVoltage	string	Resting-voltage component rating (e.g. `"Good"`, `"Fair"`, `"Bad"`)
crankVoltage	string	Cranking-voltage component rating
trend	string	Voltage-trend component rating
decay	string	Parked-decay component rating
chargeAcceptance	string	Charge-acceptance component rating
latestReading	string	Latest-reading component rating

Example response

{
  "currentVoltage": 12.9,
  "isEngineOn": true,
  "voltageHistory": {
    "7day": {
      "peak": 14.2,
      "average": 13.78,
      "lowest": 12.56
    },
    "30day": {
      "peak": 14.2,
      "average": 13.78,
      "lowest": 12.56
    },
    "60day": {
      "peak": 14.2,
      "average": 13.78,
      "lowest": 12.56
    },
    "90day": {
      "peak": 14.2,
      "average": 13.78,
      "lowest": 12.56
    }
  },
  "forecast": {
    "score": "90+",
    "comment": "Resting voltage remain optimal. No maintenance required"
  },
  "statuses": [
    {
      "id": 1,
      "label": "Park Drain",
      "comment": "Battery is losing charge fast while parked",
      "signalPattern": "Decay signal = 0/13 OR Slope > 0.015V/hr"
    },
    {
      "id": 2,
      "label": "Trend",
      "comment": "Battery voltage has been slowly dropping over the last 30 days",
      "signalPattern": "30 Day rest voltage slope <0.003 V/day"
    }
  ],
  "healthScore": {
    "score": 84,
    "maxScore": 100,
    "comment": "Losing charge while parked, voltage trending down, load test recommended",
    "composition": {
      "restingVoltage": "Good",
      "crankVoltage": "Good",
      "trend": "Fair",
      "decay": "Bad",
      "chargeAcceptance": "Good",
      "latestReading": "Good"
    }
  }
}

Error responses

Status	Meaning
401	Missing or invalid token

curl "https://api.telemax.com.au/api/v2/battery-health?pageNumber=1&pageSize=25&filter=0" \
  -H "Authorization: Bearer <token>"

Authorizations

Authorization

string

header

required

JWT Bearer token obtained from POST /api/v2/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 to the company the key belongs to and may restrict access to a vehicle allowlist and/or action set (see token claims).

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

Query Parameters

pageNumber

integer

default:1

Page number to retrieve (1-based). Returned as page in the response.

pageSize

integer

default:25

Number of results per page. Returned as pageSize in the response.

searchText

string

Optional filter by vehicle name.

filter

integer

default:0

Band filter: 0 = All, 1 = Critical, 2 = Warning, 3 = Healthy.

sortBy

integer

default:0

Sort field (maps to BatteryHealthSortField enum values).

sortDescending

boolean

default:false

When true, sort results in descending order.

badgeFilter

integer

default:0

Badge filter (maps to BatteryHealthBadge enum values; 0 = None / no filter).

Response

200 OK — Returns a fleet-level summary and a paginated list of per-vehicle battery health records, including voltage history, health scores, badge signals, and replacement forecasts.

summary

object

Fleet-level battery health counts and average score across all vehicles.

Show child attributes

items

object[]

Paginated list of per-vehicle battery health records.

Show child attributes

totalCount

integer

Total number of vehicles with battery health data (across all pages).

page

integer

Current page number (1-based).

pageSize

integer

Number of results returned per page.

Trip replay Webhooks overview

​Overview

​Endpoint

​Query parameters

​Response

​Top-level fields

​voltageHistory

​forecast

​statuses[]

​healthScore

​healthScore.composition

​Example response

​Error responses

Authorizations

Query Parameters

Response

Overview

Endpoint

Query parameters

Response

Top-level fields

`voltageHistory`

`forecast`

`statuses[]`

`healthScore`

`healthScore.composition`

Example response

Error responses