Temporal Benchmark Report

Compare task volume in the selected period against the immediately preceding period, with absolute and percentage change per group.

GET/apidev/v1/reports/gt/benchmark

PermissionAPICLI_RPTGT_BENCHMARK

Rate Limit10 req/min

Cache300s

Max Range92 days

---

Overview

This report measures how finished-task volume changed between the period you select and the period right before it. For each group — provider, device, driver, service type, cause, geography, date, and more — it returns the current-period count, the previous-period count, the absolute change, and the percentage change. Use it to spot trends, growth, or drop-offs across consecutive periods.

The previous period is computed automatically server-side: it is a window of the same length as your selected range, ending right where your range begins. For example, a March 1–15 request is benchmarked against February 14–28 (a 15-day window immediately before). You do not pass the previous period explicitly. 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. The previous period (same length, immediately before startdate) is computed automatically.
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

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

JavaScript

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

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/benchmark",
    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": "service_type",
        "limit": 25,
    },
)
data = response.json()

---

Response

Response Fields

Field	Type	Description
group_label	string	Display name of the group (e.g. service type, driver, provider).
group_id	string | null	Internal ID of the group, or null when not resolvable.
total	number	Current-period finished-task count (same as valor_actual).
valor_actual	number	Finished tasks in the selected period.
valor_anterior	number	Finished tasks in the previous period (same length, immediately before).
delta	number	Absolute change (valor_actual - valor_anterior).
delta_pct	number	Percentage change versus the previous period. When the previous period is 0, this is 100 if the current period has tasks, otherwise 0.

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Maintenance",
      "group_id": "42",
      "total": 320,
      "valor_actual": 320,
      "valor_anterior": 268,
      "delta": 52,
      "delta_pct": 19.4
    }
  ],
  "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.

---

Related

• SLA Multi-level Report
• Fleet Efficiency Report
• Quantity of Service Report
• Pagination