Demand vs Capacity Report

Per-shift saturation — available working minutes versus minutes spent on tasks, with a saturation percentage and an over/under/optimal classification for each driver shift.

GET/apidev/v1/reports/gt/demand-capacity

PermissionAPICLI_RPTGT_DEMANDACAPACIDAD

Rate Limit10 req/min

Cache300s

Max Range92 days

---

Overview

This report contrasts how much working time each driver shift had available against how much of it was actually spent on tasks. For every recorded shift it returns the available minutes (clipped to the requested window and net of breaks), the minutes used on finished tasks, a saturation percentage, the number of tasks assigned, an estimated backlog left at close, and a classification of the shift as over-utilized (sobrecarga), under-utilized (subutilizacion), or optimal (optimo).

Unlike the other GT Advanced reports, results are returned one row per driver shift — they are not grouped by a chosen dimension. The group_by, sla_threshold_minutes, and revisit_window_days parameters do not apply to this report and are ignored if sent. Standard GT filters (device, driver, service type, etc.) narrow the tasks counted within each shift.

---

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.
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.

group_by, sla_threshold_minutes, and revisit_window_days are accepted by the shared query schema but have no effect on this report.

---

Code Examples

cURL

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

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/demand-capacity?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&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/demand-capacity",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={"startdate": "2026-03-01T00:00:00", "enddate": "2026-03-15T23:59:59", "limit": 25},
)
data = response.json()

---

Response

Response Fields

Field	Type	Description
conjorlabid	number	Shift (work session) ID.
conjorconid	number	Driver ID associated with the shift.
connom	string	Driver name (Sin nombre when not resolvable).
conjorinifch	string	Shift start date-time.
conjorfinfch	string	Shift end date-time (clipped to the requested window).
minutos_disponibles	number	Available working minutes, net of breaks.
minutos_usados_tareas	number	Minutes spent on finished tasks during the shift.
porcentaje_saturacion	number	Saturation percentage (minutes used / minutes available * 100).
clasificacion	string	Shift classification: sobrecarga (over), subutilizacion (under), or optimo (optimal).
tareas_asignadas	number	Distinct finished tasks assigned during the shift.
backlog_estimado	number	Estimated tasks still pending at the close of the shift's day.

Example Response

{
  "success": true,
  "data": [
    {
      "conjorlabid": 88123,
      "conjorconid": 10293,
      "connom": "Carlos Martinez",
      "conjorinifch": "2026-03-03T08:00:00",
      "conjorfinfch": "2026-03-03T17:00:00",
      "minutos_disponibles": 480,
      "minutos_usados_tareas": 522,
      "porcentaje_saturacion": 108.75,
      "clasificacion": "sobrecarga",
      "tareas_asignadas": 14,
      "backlog_estimado": 3
    }
  ],
  "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

• Fleet Efficiency Report
• Productivity Report
• Delay Bands Report
• Pagination