Task Kilometers Report

Distance metrics per task grouping — total, average, max, and per-task kilometers.

GET/apidev/v1/reports/gt/gt-kilometers

PermissionAPICLI_RPTGT_KM

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Query Parameters

Parameter	Type	Required	Default	Description
startdate	string	Yes	—	ISO 8601 start date-time
enddate	string	Yes	—	ISO 8601 end date-time. Max range 31 days
devices	string	No	All visible	Comma-separated device IDs. Max 500
drivers	string	No	All	Comma-separated driver IDs. Max 500
service_types	string	No	All	Comma-separated service type IDs. Max 100
causes	string	No	All	Comma-separated cause IDs. Max 100
subcauses	string	No	All	Comma-separated subcause IDs. Max 100
statuses	string	No	All	Comma-separated status codes. Max 100
device_groups	string	No	All	Comma-separated device group IDs. Max 100
origins	string	No	All	Comma-separated origin IDs. Max 100
providers	string	No	All	Comma-separated provider IDs. Max 100
route_ids	string	No	All	Comma-separated route IDs. Max 100
operators	string	No	All	Comma-separated operator IDs. Max 100
client_id	string	No	—	Filter by specific client
account_id	string	No	—	Filter by specific account
shift_id	string	No	—	Filter by specific shift
date_field	enum	No	—	Date field to filter on: CREATED, SCHEDULED, FINISHED
group_by	enum	No	—	Grouping dimension (see below)
limit	integer	No	25	Records per page (1–100)
offset	integer	No	0	Records to skip

group_by values

DATE · MONTH · HOUR · WEEKDAY · DEPARTMENT · CITY · ZONE · PROVIDER · DEVICE · DEVICE_GROUP · DRIVER · SHIFT · CAUSE · SUBCAUSE · END_CODE · ORIGIN · TELEPHONIST · OPERATOR

---

Code Examples

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/gt-kilometers?startdate=2026-03-01T00:00:00&enddate=2026-03-31T23:59:59&group_by=DEVICE&limit=25"

JavaScript

const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'X-API-Key': APIKEY,
  'tenant': TENANT,
};

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/gt-kilometers?startdate=2026-03-01T00:00:00&enddate=2026-03-31T23:59:59&group_by=DEVICE&limit=25`,
  { headers }
);
const data = await res.json();

Python

import requests

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-API-Key": APIKEY,
    "tenant": TENANT,
}

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/gt-kilometers",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-31T23:59:59",
        "group_by": "DEVICE",
        "limit": 25,
    },
)
data = response.json()

---

Response Fields

Field	Type	Description
group_label	string	Display name of the group
group_id	string | null	Identifier of the group element
total_tasks	number	Total number of tasks
total_kms	number	Total kilometers across all tasks
avg_kms	number	Average kilometers per task
max_kms	number	Maximum kilometers for a single task
kms_per_task	number	Kilometers per task ratio

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "104820579301",
      "total_tasks": 47,
      "total_kms": 892.3,
      "avg_kms": 18.98,
      "max_kms": 45.2,
      "kms_per_task": 18.98
    },
    {
      "group_label": "Truck B-205",
      "group_id": "104820579402",
      "total_tasks": 32,
      "total_kms": 614.7,
      "avg_kms": 19.21,
      "max_kms": 52.8,
      "kms_per_task": 19.21
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
BAD_REQUEST	400	Missing required headers
VALIDATION_ERROR	400	Invalid params: missing dates, range > 31 days, invalid group_by
UNAUTHORIZED	401	Invalid or expired JWT / API Key
FORBIDDEN	403	User lacks required permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Quantity of Services
• Total Service Time
• Arrival Time
• Delay Bands
• Pagination