Control Arrival Time Report

Arrival time distribution across time bands per grouping.

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

PermissionAPICLI_RPTGT_CTLL

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Overview

Returns how arrival times spread across fixed time bands (0–15, 15–30, 30–45, 45–60, and 60+ minutes), with the task count in each band plus the average, aggregated by a chosen grouping dimension. Use it to see the shape of your response times, not just the 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

This report does not match the "Promised Arrival Time Control" screen yet

The web screen with the same name measures something different: it compares each task's actual arrival time against the time promised to the customer and reports how many were met, how many were exceeded, and the compliance percentage. This endpoint returns arrival time bands instead, and its avg_time_sec is the average travel time in seconds (the screen shows minutes). Do not reconcile the two side by side. Aligning this endpoint 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-arrival-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-arrival-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-arrival-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_15	number	Tasks with arrival time 0–15 min
band_15_30	number	Tasks with arrival time 15–30 min
band_30_45	number	Tasks with arrival time 30–45 min
band_45_60	number	Tasks with arrival time 45–60 min
band_60_plus	number	Tasks with arrival time > 60 min
avg_time_sec	number	Average arrival time in seconds

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "104820579301",
      "total_tasks": 47,
      "band_0_15": 18,
      "band_15_30": 12,
      "band_30_45": 8,
      "band_45_60": 5,
      "band_60_plus": 4,
      "avg_time_sec": 1560
    },
    {
      "group_label": "Truck B-205",
      "group_id": "104820579402",
      "total_tasks": 32,
      "band_0_15": 10,
      "band_15_30": 9,
      "band_30_45": 6,
      "band_45_60": 4,
      "band_60_plus": 3,
      "avg_time_sec": 1740
    }
  ],
  "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

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