Battery health

Battery health (V2)

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.telemax.com.au/v2/api/battery-health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.telemax.com.au/v2/api/battery-health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.telemax.com.au/v2/api/battery-health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.telemax.com.au/v2/api/battery-health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "type": "AUTHENTICATION",
  "code": "INVALID_CREDENTIALS",
  "description": "The provided API key is invalid or does not exist.",
  "requestId": "0HNLTALNU4DCO:00000004",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-credentials"
}

{
  "type": "AUTHORIZATION",
  "code": "INVALID_SCOPE",
  "description": "The provided token does not have permission to access this resource.",
  "requestId": "50e5c5f7-ccae-4ab6-b070-56d6645ceb1e",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-scope"
}

{
  "type": "RATE_LIMIT",
  "code": "RATE_LIMIT_EXCEEDED",
  "description": "Too many requests. Please slow down.",
  "requestId": "req_6d2f8b4a",
  "docUrl": "https://docs.telemax.com.au/errors/rate-limit-exceeded"
}

{
  "type": "SERVER_ERROR",
  "code": "INTERNAL_SERVER_ERROR",
  "description": "An unexpected error occurred. Please try again later.",
  "requestId": "req_1e5a3c7d",
  "docUrl": "https://docs.telemax.com.au/errors/internal-server-error"
}

GET

api

battery-health

Battery health (V2)

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.telemax.com.au/v2/api/battery-health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.telemax.com.au/v2/api/battery-health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.telemax.com.au/v2/api/battery-health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.telemax.com.au/v2/api/battery-health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "type": "AUTHENTICATION",
  "code": "INVALID_CREDENTIALS",
  "description": "The provided API key is invalid or does not exist.",
  "requestId": "0HNLTALNU4DCO:00000004",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-credentials"
}

{
  "type": "AUTHORIZATION",
  "code": "INVALID_SCOPE",
  "description": "The provided token does not have permission to access this resource.",
  "requestId": "50e5c5f7-ccae-4ab6-b070-56d6645ceb1e",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-scope"
}

{
  "type": "RATE_LIMIT",
  "code": "RATE_LIMIT_EXCEEDED",
  "description": "Too many requests. Please slow down.",
  "requestId": "req_6d2f8b4a",
  "docUrl": "https://docs.telemax.com.au/errors/rate-limit-exceeded"
}

{
  "type": "SERVER_ERROR",
  "code": "INTERNAL_SERVER_ERROR",
  "description": "An unexpected error occurred. Please try again later.",
  "requestId": "req_1e5a3c7d",
  "docUrl": "https://docs.telemax.com.au/errors/internal-server-error"
}

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: 4 req/s · 30/min · 600/hr · 14,400/day

Endpoint

GET /v2/api/battery-health

Query parameters

integer

default:"1"

Page number (1-based).

integer

default:"25"

Number of results per page.

string

Optional filter by vehicle name.

integer

default:"0"

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

integer

default:"0"

Sort field (maps to BatteryHealthSortField enum values).

boolean

default:"false"

When true, sort results in descending order.

integer

default:"0"

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

Response

200 OK — BatteryHealthResponse

Top-level fields

Field	Type	Description
summary	object	Fleet-level counts and average score — see below
items	array	Paged list of per-vehicle battery health objects — see below
totalCount	integer	Total number of vehicles matching the current filter (before pagination)
page	integer	Current page number (1-based)
pageSize	integer	Number of items per page

`summary`

Field	Type	Description
healthyCount	integer	Number of vehicles with a Healthy or Excellent band
warningCount	integer	Number of vehicles with a Fair or Poor band
criticalCount	integer	Number of vehicles with a Critical band
avgScore	number	Average health score across all company vehicles for the latest scored date

`items[]`

Each element in items represents one vehicle.

Field	Type	Description
vehicleId	integer	Vehicle identifier
vehicleName	string	Vehicle display name
imei	string \| null	Tracker IMEI when known
currentVoltage	number \| null	Latest observed battery voltage (V)
isEngineOn	boolean \| null	Whether the engine was running at the time of the reading
band	string \| null	Health band classification: `"Critical"`, `"Warning"`, or `"Healthy"`
badges	string[]	Active badge identifiers for this vehicle (e.g. `"DEEP_DISCHARGE"`, `"ALTERNATOR"`, `"PARK_DRAIN"`). Used for display and filtering
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
last90DaysVoltage	array	Daily average voltage readings for the last 90 days — see below
daysToReplace	integer \| null	Days until battery replacement is recommended; `null` when not applicable or unavailable
scoredOn	string \| null	ISO 8601 date the health score was last calculated (e.g. `"2026-06-07"`)
restScore	integer \| null	Raw resting-voltage component score
crankScore	integer \| null	Raw cranking-voltage component score
trendScore	integer \| null	Raw voltage-trend component score
decayScore	integer \| null	Raw parked-decay component score
chargeScore	integer \| null	Raw charge-acceptance component score
latestScore	integer \| null	Raw latest-reading component score

`voltageHistory`

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

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

`forecast`

Field	Type	Description
score	integer \| null	Composite health score (0–100); `null` when not yet available
comment	string	Human-readable forecast summary based on `daysToReplace`

`statuses[]`

Field	Type	Description
id	string \| null	Stable status identifier (e.g. `"PARK_DRAIN"`)
label	string \| null	Short display label (e.g. `"Park Drain"`)
comment	string \| null	Human-readable description of the condition
signalPattern	string \| null	Signal rule that triggered this status

`healthScore`

Field	Type	Description
score	integer \| null	Overall health score (0–100); `null` when not computable
maxScore	integer	Maximum possible score (always `100`)
comment	string	Human-readable summary of the overall score
composition	object	Per-component ratings — see below

`healthScore.composition`

Each field is a string rating derived from the component’s raw score relative to its maximum.

Field	Type	Values
restingVoltage	string	`"Good"`, `"Fair"`, `"Bad"`, or `"grey"` (insufficient data)
crankVoltage	string	`"Good"`, `"Fair"`, `"Bad"`, or `"grey"`
trend	string	`"Good"`, `"Fair"`, `"Bad"`, or `"grey"`
decay	string	`"Good"`, `"Fair"`, `"Bad"`, or `"grey"`
chargeAcceptance	string	`"Good"`, `"Fair"`, `"Bad"`, or `"grey"`
latestReading	string	`"Good"`, `"Fair"`, `"Bad"`, or `"grey"`

`last90DaysVoltage[]`

Daily voltage readings for trend visualisation. May be an empty array if data is unavailable.

Field	Type	Description
date	string	ISO 8601 calendar date (e.g. `"2026-06-07"`)
voltage	number \| null	Average external battery voltage for that day (V)

Example response

{
  "summary": {
    "healthyCount": 18,
    "warningCount": 4,
    "criticalCount": 1,
    "avgScore": 76
  },
  "items": [
    {
      "vehicleId": 1042,
      "vehicleName": "Fleet Van 03",
      "imei": "357647131029365",
      "currentVoltage": 12.9,
      "isEngineOn": false,
      "band": "Healthy",
      "badges": [],
      "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.72, "lowest": 12.41 },
        "90day": { "peak": 14.3, "average": 13.69, "lowest": 12.21 }
      },
      "forecast": {
        "score": 84,
        "comment": "AI analysis predicts optimal performance and voltage retention for the next 90+ days."
      },
      "statuses": [],
      "healthScore": {
        "score": 84,
        "maxScore": 100,
        "comment": "Battery health is good.",
        "composition": {
          "restingVoltage": "Good",
          "crankVoltage": "Good",
          "trend": "Fair",
          "decay": "Good",
          "chargeAcceptance": "Good",
          "latestReading": "Good"
        }
      },
      "last90DaysVoltage": [
        { "date": "2026-06-07", "voltage": 12.9 },
        { "date": "2026-06-06", "voltage": 13.1 }
      ],
      "daysToReplace": 120,
      "scoredOn": "2026-06-07",
      "restScore": 18,
      "crankScore": 15,
      "trendScore": 10,
      "decayScore": 13,
      "chargeScore": 14,
      "latestScore": 14
    }
  ],
  "totalCount": 23,
  "page": 1,
  "pageSize": 25
}

Error responses

Status	Meaning
401	Missing or invalid token
403	Token does not have access to battery health data

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

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 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.

Getting Started

Guides

Authentication

Companies & fleet

Vehicles

Vehicle commands

Alerts

Telemetry & replay

Insights & diagnostics

Webhooks

Reference

Overview

Endpoint

Query parameters

Response

Top-level fields

`summary`

`items[]`

`voltageHistory`

`forecast`

`statuses[]`

`healthScore`

`healthScore.composition`

`last90DaysVoltage[]`

Example response

Error responses

Authorizations

Query Parameters

Response

​Overview

​Endpoint

​Query parameters

​Response

​Top-level fields

​summary

​items[]

​voltageHistory

​forecast

​statuses[]

​healthScore

​healthScore.composition

​last90DaysVoltage[]

​Example response

​Error responses

Authorizations

Query Parameters

Response

Overview

Endpoint

Query parameters

Response

Top-level fields

`summary`

`items[]`

`voltageHistory`

`forecast`

`statuses[]`

`healthScore`

`healthScore.composition`

`last90DaysVoltage[]`

Example response

Error responses