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 take date parameters — it returns the current state of every maintenance program.

• Default view — programs that are on track (next_service_value > 0)
• Overdue detection — overdue_only=true switches to programs past due (next_service_value <= 0)
• Program filtering — maintenance_ids restricts to specific maintenance programs
• Unit-aware values — service values are in kilometers or engine hours depending on maintenance_period; the backend resolves the period type

No date range

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

---

Request

Request Headers

Every request to a protected endpoint requires these headers:

Header	Required	Description
Authorization	Yes	Bearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-Key	Yes	Company integration key provided during onboarding. Format: gtk_xxx...
tenant	Yes	Your assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

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 program IDs. Max 100
overdue_only	boolean	No	false	false returns programs on track (next_service_value > 0); true returns overdue programs (next_service_value <= 0)
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_name	string	Name of the maintenance program (e.g. "Oil Change 7500 km")
maintenance_period	string	Period type: "Kms recorridos" (kilometers), "Horas de ignición" (engine hours), "Cada cantidad de días" (every N days), or "Fecha específica" (specific date). For day/date-based periods the value fields are null
maintenance_value	number	Configured service interval of the program (e.g. every 7500 km)
device_name	string	Display name of the vehicle/device
last_service_value	number | null	Odometer/horometer reading at the last completed service. null if never serviced
next_service_value	number | null	Amount remaining until the next service. <= 0 means overdue
current_value	number | null	Current odometer/horometer reading of the vehicle
remaining_value	number | null	Amount consumed since the last service

Kilometers or hours

maintenance_value, last_service_value, next_service_value, current_value, and remaining_value are expressed in kilometers or engine hours depending on maintenance_period.

Example Response

{
  "success": true,
  "data": [
    {
      "maintenance_name": "Service 7500 km",
      "maintenance_period": "Kms recorridos",
      "maintenance_value": 7500,
      "device_name": "Truck A-101",
      "last_service_value": 191175,
      "next_service_value": 130,
      "current_value": 198545,
      "remaining_value": 7370
    },
    {
      "maintenance_name": "Oil Change 10000 km",
      "maintenance_period": "Kms recorridos",
      "maintenance_value": 10000,
      "device_name": "Van B-205",
      "last_service_value": 55200,
      "next_service_value": 400,
      "current_value": 64800,
      "remaining_value": 9600
    }
  ],
  "meta": {
    "total": 12,
    "limit": 50,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid params: non-numeric IDs, limit > 100, > 500 devices, > 100 maintenance_ids
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-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