Skip to main content

Proactivity by Device Report

Device-level task compliance for a specific execution date — summary + per-device breakdown.

GET/apidev/v1/reports/gt/proactivity-device
PermissionAPICLI_RPTGT_PROACTIVIDAD_DISP
Rate Limit10 req/min
Cache60s (1 min)

Overview​

Returns task compliance for a single execution date, grouped by device type — exactly what the Proactivity screen shows. Each group carries its own subtotal row (summary) and its own per-device breakdown (devices): driver, shift, task counts, unassigned time, occupancy and average times. Set realtime=true for live figures, and filter by devices, drivers, service types, causes, geography, or geofences.

Breaking change — 2026-08-17

data is now an array of device-type groups. It used to be a single { summary, devices } object built from the first group only, which silently dropped every other device type (a fleet with cars and motorcycles got cars only). See Response.

Request​

Request Headers​

Every request to a protected endpoint requires these headers:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-TypeConditionalapplication/json — required for POST and PUT requests

Query Parameters​

ParameterTypeRequiredDefaultDescription
execution_datestringYes—ISO 8601 date (e.g. 2026-03-19). Single date, not a range.
realtimebooleanNo—Include real-time data.
devicesstringNo—Comma-separated device IDs. Max 500.
driversstringNo—Comma-separated driver IDs. Max 500.
service_typesstringNo—Comma-separated service type IDs. Max 100.
causesstringNo—Comma-separated cause IDs. Max 100.
subcausesstringNo—Comma-separated subcause IDs. Max 100.
countriesstringNo—Comma-separated country IDs. Max 50.
departmentsstringNo—Comma-separated department IDs. Max 50.
geofencesstringNo—Comma-separated geofence IDs. Max 100.
limitintegerNo25Number of device-type groups per page (1–100).
offsetintegerNo0Number of device-type groups to skip for pagination.
Pagination applies to groups, not devices

limit / offset page the device-type groups, and meta.total is the total number of groups. Each group always carries all of its devices — a group with subtotals but no qualifying vehicle would otherwise disappear from the response.

Code Examples​

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/proactivity-device?execution_date=2026-03-19&limit=25"

Response​

data is an array of device-type groups. One element per device type (the "Tipo de móvil" grouping of the web report), each with its subtotal row and its device rows.

All durations are expressed in minutes (*_min) and are also provided pre-formatted for display (*_text, e.g. "1h 35m"). An empty *_text means the underlying figure was not computable for that group.

Group Fields​

FieldTypeDescription
device_typestringDevice type / proactivity group name.
device_type_idstring | nullDevice type identifier.
summaryobjectSubtotals for the group — see below.
devicesarrayOne row per vehicle in the group — see below.

Summary Fields​

FieldTypeDescription
device_typestringDevice type name (same as the group).
device_type_idstring | nullDevice type identifier.
total_devicesnumberActive devices in the group.
devices_freenumberActive devices with no task in progress.
total_tasksnumberConvenience sum: tasks_pending + tasks_finished + tasks_in_progress + tasks_cancelled. Not a column of the web report.
tasks_finishednumberFinished tasks.
tasks_pendingnumberUnassigned tasks (not scheduled).
tasks_pending_schedulednumberUnassigned tasks scheduled for a future time.
tasks_in_progressnumberTasks in progress.
tasks_cancellednumberCancelled tasks.
tasks_rejectednumberTasks rejected by drivers.
max_time_unassigned_min / _textnumber / stringLongest time a vehicle went without an assignment.
compliance_pctnumberOccupancy: share of the shift spent on tasks.
avg_arrival_last_hour_min / _textnumber / stringAverage arrival time over the last hour.
avg_arrival_day_min / _textnumber / stringAverage arrival time for the day.
avg_assignment_min / _textnumber / stringAverage time to assign a task.
avg_arrival_min / _textnumber / stringAverage time from acceptance to arrival.
avg_on_task_min / _textnumber / stringAverage time spent on task.
avg_kmnumberAverage kilometres per finished task.

Devices Array Fields​

FieldTypeDescription
device_idstring | nullDevice identifier.
device_namestringVehicle name.
driver_idstring | nullDriver identifier.
driver_namestringDriver name.
activebooleanThe vehicle has an open shift on the execution date.
worked_min / worked_textnumber / stringDriver shift length.
total_tasksnumbertasks_finished + tasks_in_progress + tasks_cancelled + tasks_rejected.
tasks_finishednumberFinished tasks.
tasks_in_progressnumberTasks in progress.
tasks_cancellednumberCancelled tasks.
tasks_rejectednumberTasks rejected by the driver.
time_unassigned_min / _textnumber / stringLongest stretch without an assignment.
compliance_pctnumberOccupancy of this vehicle's shift.
avg_arrival_day_min / _textnumber / stringAverage arrival time for the day.
avg_assignment_min / _textnumber / stringAverage time to assign.
avg_arrival_min / _textnumber / stringAverage time from acceptance to arrival.
avg_on_task_min / _textnumber / stringAverage time on task.
last_signal_min / _textnumber / stringTime since the last signal received.
last_gps_min / _textnumber / stringTime since the last valid GPS fix.
total_kmnumberKilometres driven on finished tasks.
avg_kmnumberAverage kilometres per finished task.
time_since_last_task_min / _textnumber / stringTime since the last finished task (0 while a task is in progress).
avg_arrival_last_hour_min / _textnumber / stringAverage arrival time over the last hour.
tasks_pending was removed from the device rows

It was derived by subtraction and always resolved to the rejected-task count. "Unassigned" is a group-level concept and lives in summary.tasks_pending; the per-vehicle rejected count is now published as tasks_rejected.

Example Response​

{
  "success": true,
  "data": [
    {
      "device_type": "Cars",
      "device_type_id": "104820570001",
      "summary": {
        "device_type": "Cars",
        "device_type_id": "104820570001",
        "total_devices": 5,
        "devices_free": 2,
        "total_tasks": 47,
        "tasks_finished": 35,
        "tasks_pending": 8,
        "tasks_pending_scheduled": 2,
        "tasks_in_progress": 3,
        "tasks_cancelled": 1,
        "tasks_rejected": 0,
        "max_time_unassigned_min": 95,
        "max_time_unassigned_text": "1h 35m",
        "compliance_pct": 74,
        "avg_arrival_last_hour_min": 18,
        "avg_arrival_last_hour_text": "18m",
        "avg_arrival_day_min": 22,
        "avg_arrival_day_text": "22m",
        "avg_assignment_min": 4,
        "avg_assignment_text": "4m",
        "avg_arrival_min": 19,
        "avg_arrival_text": "19m",
        "avg_on_task_min": 41,
        "avg_on_task_text": "41m",
        "avg_km": 12.4
      },
      "devices": [
        {
          "device_id": "104820579301",
          "device_name": "Truck A-101",
          "driver_id": "104820561122",
          "driver_name": "Carlos Martinez",
          "active": true,
          "worked_min": 480,
          "worked_text": "8h",
          "total_tasks": 12,
          "tasks_finished": 10,
          "tasks_in_progress": 1,
          "tasks_cancelled": 1,
          "tasks_rejected": 0,
          "time_unassigned_min": 35,
          "time_unassigned_text": "35m",
          "compliance_pct": 83,
          "avg_arrival_day_min": 20,
          "avg_arrival_day_text": "20m",
          "avg_assignment_min": 3,
          "avg_assignment_text": "3m",
          "avg_arrival_min": 17,
          "avg_arrival_text": "17m",
          "avg_on_task_min": 39,
          "avg_on_task_text": "39m",
          "last_signal_min": 2,
          "last_signal_text": "2m",
          "last_gps_min": 2,
          "last_gps_text": "2m",
          "total_km": 124.5,
          "avg_km": 12.45,
          "time_since_last_task_min": 0,
          "time_since_last_task_text": "",
          "avg_arrival_last_hour_min": 15,
          "avg_arrival_last_hour_text": "15m"
        }
      ]
    },
    {
      "device_type": "Motorcycles",
      "device_type_id": "104820570002",
      "summary": {
        "device_type": "Motorcycles",
        "device_type_id": "104820570002",
        "total_devices": 2,
        "devices_free": 1,
        "total_tasks": 9,
        "tasks_finished": 7,
        "tasks_pending": 1,
        "tasks_pending_scheduled": 0,
        "tasks_in_progress": 1,
        "tasks_cancelled": 0,
        "tasks_rejected": 0,
        "max_time_unassigned_min": 40,
        "max_time_unassigned_text": "40m",
        "compliance_pct": 61,
        "avg_arrival_last_hour_min": 11,
        "avg_arrival_last_hour_text": "11m",
        "avg_arrival_day_min": 13,
        "avg_arrival_day_text": "13m",
        "avg_assignment_min": 2,
        "avg_assignment_text": "2m",
        "avg_arrival_min": 12,
        "avg_arrival_text": "12m",
        "avg_on_task_min": 28,
        "avg_on_task_text": "28m",
        "avg_km": 6.2
      },
      "devices": []
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

Errors​

CodeHTTPDescription
VALIDATION_ERROR400Invalid params: missing execution_date, invalid enum values.
UNAUTHORIZED401Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN403User lacks required permission.
RATE_LIMITED429Exceeded 10 req/min.
INTERNAL_ERROR500Unexpected server error.