Control Total Time Report

Total service time distribution across time bands per grouping.

GET/apidev/v1/reports/gt/control-total-time

PermissionAPICLI_RPTGT_CTT

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Overview

Returns how total service times spread across fixed time bands (0–30 min, 30–60 min, 1–2 h, 2–3 h, and 3+ h), with the task count in each band plus the average, aggregated by a chosen grouping dimension. Use it to understand the distribution of overall service duration, not just a single average.

• Grouping — group_by picks the dimension each row represents (see the values below)
• Date basis — the date range always filters on the task finished date (startdate/enddate)
• Filtering — narrow results by devices, drivers, service types, providers, and other catalog filters

The bands differ from the "Total Time Control" screen

The web screen groups tasks by the full cycle time (from the call to the finish) into Fast 0–60 min, Normal 60–120, Extended 120–240, Long 240–480 and Very long 480+. This endpoint bands the working time instead, cut at 0–30 / 30–60 min and 1–2 / 2–3 / 3+ h, so only the 1–2 h band lines up. Its avg_time_sec is in seconds, while the screen shows minutes. Do not reconcile the two side by side. Aligning the bands with the screen is planned and will change the response fields.

---

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
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
device_groups	string	No	All	Comma-separated device type IDs (the device_group catalog from Fleet / Devices). Filters tasks to devices of those types; combines with devices as an intersection. 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
group_by	enum	No	—	Grouping dimension (see below)
limit	integer	No	25	Records per page (1–100)
offset	integer	No	0	Records to skip

How device_groups combines with devices

device_groups is expanded to every device of those types, and if you also send devices, only the devices present in both lists are kept. If that intersection is empty the report returns no rows.

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/control-total-time?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/control-total-time?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/control-total-time",
    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
band_0_30	number	Tasks completed in 0–30 min
band_30_60	number	Tasks completed in 30–60 min
band_1_2hrs	number	Tasks completed in 1–2 hours
band_2_3hrs	number	Tasks completed in 2–3 hours
band_3_plus	number	Tasks completed in > 3 hours
avg_time_sec	number	Average total time in seconds

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "104820579301",
      "total_tasks": 47,
      "band_0_30": 5,
      "band_30_60": 14,
      "band_1_2hrs": 18,
      "band_2_3hrs": 7,
      "band_3_plus": 3,
      "avg_time_sec": 4920
    },
    {
      "group_label": "Truck B-205",
      "group_id": "104820579402",
      "total_tasks": 32,
      "band_0_30": 3,
      "band_30_60": 10,
      "band_1_2hrs": 12,
      "band_2_3hrs": 5,
      "band_3_plus": 2,
      "avg_time_sec": 5280
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

---

Errors

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

---

Related

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