Time-window Compliance Report

Did finished tasks start inside their scheduled window? Counts of early, on-time, and late starts per group, with average deviation.

GET/apidev/v1/reports/gt/time-window-compliance

PermissionAPICLI_RPTGT_CUMPLIMIENTOVENTANA

Rate Limit10 req/min

Cache300s

Max Range92 days

Overview

For finished tasks that had a scheduled window, this report compares the actual start time against the planned window and classifies each task as early (started before the window), on-time (started inside the window), or late (started after the window). Results are aggregated per group — by provider, device, driver, service type, cause, geography, date, and more — and include the average start deviation in minutes and an on-time compliance percentage.

Only tasks with both a valid scheduled start and a valid scheduled end are classified; tasks without a scheduled window do not contribute to the early/on-time/late counts. Choose how rows are grouped with group_by (defaults to provider).

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 (e.g. `2026-03-01T00:00:00`).
`enddate`	string	Yes	—	ISO 8601 end date-time. Max range 92 days from `startdate`.
`group_by`	string	No	`provider`	How rows are grouped. One of: `provider`, `device`, `driver`, `cause`, `subcause`, `service_type`, `product`, `origin`, `shift`, `end_code`, `comm_media`, `route`, `country`, `department`, `city`, `zone`, `client`, `telephonist`, `operator`, `resource_type`, `date`, `month`, `weekday`, `hour`.
`devices`	string	No	—	Comma-separated device IDs. Max 500.
`drivers`	string	No	—	Comma-separated driver IDs. Max 500.
`providers`	string	No	—	Comma-separated provider IDs. Max 100.
`service_types`	string	No	—	Comma-separated service type IDs. Max 100.
`causes`	string	No	—	Comma-separated cause IDs. Max 100.
`subcauses`	string	No	—	Comma-separated subcause IDs. Max 100.
`statuses`	string	No	—	Comma-separated task status codes. 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	—	Comma-separated origin IDs. Max 100.
`route_ids`	string	No	—	Comma-separated route IDs. Max 100.
`operators`	string	No	—	Comma-separated operator IDs. Max 100.
`client_id`	string	No	—	Single client ID.
`account_id`	string	No	—	Single account ID.
`shift_id`	string	No	—	Single shift ID.
`limit`	integer	No	`25`	Number of records per page (`1`–`100`).
`offset`	integer	No	`0`	Number of records to skip for pagination.

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.

Code Examples

cURL
JavaScript
Python

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

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/time-window-compliance?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=driver&limit=25`,
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);
const data = await res.json();

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/time-window-compliance",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "group_by": "driver",
        "limit": 25,
    },
)
data = response.json()

Response

Response Fields

Field	Type	Description
`group_label`	string	Display name of the group (e.g. driver, device, provider).
`group_id`	string \| null	Internal ID of the group, or `null` when not resolvable.
`total`	number	Total finished tasks in the group.
`antes`	number	Tasks that started before the scheduled window (early).
`dentro`	number	Tasks that started inside the scheduled window (on-time).
`despues`	number	Tasks that started after the scheduled window (late).
`desfase_promedio_min`	number	Average start deviation versus the planned start, in minutes.
`cumplimiento_pct`	number	On-time compliance percentage (`dentro / total * 100`).

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Carlos Martinez",
      "group_id": "10293",
      "total": 120,
      "antes": 14,
      "dentro": 95,
      "despues": 11,
      "desfase_promedio_min": -3.42,
      "cumplimiento_pct": 79.17
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Errors

Code	HTTP	Description
`VALIDATION_ERROR`	400	Invalid params: missing dates, range > 92 days, invalid enum values.
`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.

Overview​

Request​

Request Headers​

Query Parameters​

Code Examples​

Response​

Response Fields​

Example Response​

Errors​

Related​