Maintenance Report

Current maintenance status for your fleet — remaining kilometers, hours until service, and overdue items. A real-time snapshot, no date range required.

GET/apidev/v1/reports/avl/maintenance

PermissionAPICLI_RPTAVL_MANTENIMIENTO

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

---

Overview

Real-time snapshot of preventive maintenance status. Unlike other AVL reports, this endpoint does not require date parameters — it returns the current state of every maintenance item.

• Overdue detection — overdue_only=true filters to items past their service interval
• Product filtering — maintenance_ids restricts to specific maintenance items
• Dual tracking — monitors both kilometers and engine hours

No date range

This endpoint returns current maintenance state, not historical data. No startdate/enddate required.

---

Query Parameters

Parameter	Type	Required	Default	Description
devices	string	No	All visible	Comma-separated device IDs. Max 500
maintenance_ids	string	No	All	Comma-separated maintenance product IDs. Max 100
overdue_only	boolean	No	false	Only return items past their service interval
limit	integer	No	25	Records per page (1–100)
offset	integer	No	0	Records to skip

---

Code Examples

cURL

curl -s "https://$TENANT/apidev/v1/reports/avl/maintenance?limit=50&overdue_only=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/maintenance?limit=50&overdue_only=true`,
  { headers }
);
const { data, meta } = await response.json();

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/avl/maintenance",
    headers=headers,
    params={"limit": 50, "overdue_only": True},
)
result = response.json()

---

Response Fields

Field	Type	Description
maintenance_id	string	Maintenance product identifier
maintenance_name	string	Name of the maintenance item (e.g. "Oil Change")
maintenance_period	string	Configured service interval description
device_name	string	Display name of the vehicle/device
last_service_date	string | null	Date of the last completed service. null if never serviced
last_service_cost	number | null	Cost of the last completed service
kms_last_service	number	Odometer reading at last service (km)
kms_current	number	Current odometer reading (km)
kms_remaining	number	Kilometers remaining until next service. Negative = overdue
kms_overdue	boolean	Whether the km-based interval has been exceeded
hrs_last_service	number	Engine hours at last service
hrs_current	number	Current engine hours
hrs_remaining	number	Engine hours remaining until next service. Negative = overdue
hrs_overdue	boolean	Whether the hours-based interval has been exceeded

Example Response

{
  "success": true,
  "data": [
    {
      "maintenance_id": "104820579600",
      "maintenance_name": "Oil Change",
      "maintenance_period": "Every 10,000 km",
      "device_name": "Truck A-101",
      "last_service_date": "2026-01-15",
      "last_service_cost": 120.50,
      "kms_last_service": 42000,
      "kms_current": 53200,
      "kms_remaining": -1200,
      "kms_overdue": true,
      "hrs_last_service": 1800,
      "hrs_current": 2150,
      "hrs_remaining": 150,
      "hrs_overdue": false
    },
    {
      "maintenance_id": "104820579601",
      "maintenance_name": "Tire Rotation",
      "maintenance_period": "Every 20,000 km",
      "device_name": "Truck A-101",
      "last_service_date": "2025-11-20",
      "last_service_cost": 85.00,
      "kms_last_service": 35000,
      "kms_current": 53200,
      "kms_remaining": 1800,
      "kms_overdue": false,
      "hrs_last_service": 0,
      "hrs_current": 0,
      "hrs_remaining": 0,
      "hrs_overdue": false
    }
  ],
  "meta": {
    "total": 12,
    "limit": 50,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
BAD_REQUEST	400	Missing required headers
VALIDATION_ERROR	400	Invalid params: non-numeric IDs, limit > 100, > 500 devices
UNAUTHORIZED	401	Invalid or expired JWT / API Key
FORBIDDEN	403	User lacks APICLI_RPTAVL_MANTENIMIENTO permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Devices API — Get device IDs and current odometer
• Ignition Report — Engine hours tracking
• Pagination — Standard pagination parameters