Skip to main content

Proactivity by Task Report

Task-level compliance detail for a specific execution date — summary + individual task records.

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

Overview​

Returns task compliance for a single execution date, grouped by device type and detailed task by task — exactly what the Proactivity by Task screen shows. Each group carries its subtotal row (summary) and its task rows (tasks) with the call / assignment / acceptance / completion timestamps and the elapsed times between them. The screen's bottom totals row is returned in meta.totals. 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, tasks } object built from the first group only, which silently dropped every other device type. Eight task fields that the reporting engine never populated were also removed — 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 tasks

limit / offset page the device-type groups, and meta.total is the total number of groups (the totals row is not counted). Each group always carries all of its tasks.

Code Examples​

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/proactivity-task?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 task rows.

All durations are expressed in minutes (*_min); the group subtotals also ship a pre-formatted *_text (e.g. "1h 35m"). Timestamps use YYYY-MM-DDTHH:mm:ss with no timezone; a stage the task never reached comes back as null.

Group Fields​

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

Summary Fields​

FieldTypeDescription
device_typestringDevice type name (same as the group).
device_type_idstring | nullDevice type identifier.
tasks_pendingnumberUnassigned tasks.
tasks_pending_schedulednumberUnassigned tasks scheduled for a future time.
tasks_in_progressnumberTasks in progress.
tasks_finishednumberFinished tasks.
tasks_cancellednumberCancelled tasks.
max_time_unassigned_min / _textnumber / stringLongest time a task stayed without a vehicle.
avg_arrival_day_min / _textnumber / stringAverage arrival time for the day.
avg_on_task_min / _textnumber / stringAverage time spent on task.
longest_wait_min / _textnumber / stringLongest wait of a single task (entry to acceptance).
avg_kmnumberAverage kilometres per task.

Tasks Array Fields​

FieldTypeDescription
task_idstring | nullTask identifier.
task_numberstring | nullTask number.
called_atstring | nullCall / entry timestamp.
assigned_atstring | nullAssignment timestamp.
accepted_atstring | nullAcceptance timestamp.
finished_atstring | nullCompletion timestamp.
scheduled_atstring | nullScheduled timestamp (null when not scheduled).
wait_minnumberEntry → acceptance.
call_to_start_minnumberEntry → start of the task.
accept_to_start_minnumberAcceptance → start of the task.
on_task_minnumberAcceptance → completion.
time_unassigned_minnumberTime the task stayed without a vehicle.

Totals Row​

meta.totals mirrors the totals row shown at the bottom of the web report. It uses the same fields as summary, with device_type: "Totales", and only the counters plus avg_arrival_day_* / avg_on_task_* are meaningful. It is null when the report produced no rows.

Fields removed on 2026-08-17

device_name, driver_name, service_type, cause, status, started_at, client_name and account_name were dropped. The reporting engine builds the task detail from identifiers, timestamps and elapsed times only, so those eight fields always came back empty. Use Tasks General — joining on task_id — for the descriptive attributes of a task.

Example Response​

{
  "success": true,
  "data": [
    {
      "device_type": "Cars",
      "device_type_id": "104820570001",
      "summary": {
        "device_type": "Cars",
        "device_type_id": "104820570001",
        "tasks_pending": 8,
        "tasks_pending_scheduled": 2,
        "tasks_in_progress": 3,
        "tasks_finished": 35,
        "tasks_cancelled": 1,
        "max_time_unassigned_min": 95,
        "max_time_unassigned_text": "1h 35m",
        "avg_arrival_day_min": 22,
        "avg_arrival_day_text": "22m",
        "avg_on_task_min": 41,
        "avg_on_task_text": "41m",
        "longest_wait_min": 64,
        "longest_wait_text": "1h 4m",
        "avg_km": 12.4
      },
      "tasks": [
        {
          "task_id": "104820580001",
          "task_number": "58231",
          "called_at": "2026-03-05T08:52:00",
          "assigned_at": "2026-03-05T08:56:00",
          "accepted_at": "2026-03-05T09:00:00",
          "finished_at": "2026-03-05T10:30:00",
          "scheduled_at": null,
          "wait_min": 8,
          "call_to_start_min": 23,
          "accept_to_start_min": 15,
          "on_task_min": 90,
          "time_unassigned_min": 4
        }
      ]
    },
    {
      "device_type": "Motorcycles",
      "device_type_id": "104820570002",
      "summary": {
        "device_type": "Motorcycles",
        "device_type_id": "104820570002",
        "tasks_pending": 1,
        "tasks_pending_scheduled": 0,
        "tasks_in_progress": 1,
        "tasks_finished": 7,
        "tasks_cancelled": 0,
        "max_time_unassigned_min": 40,
        "max_time_unassigned_text": "40m",
        "avg_arrival_day_min": 13,
        "avg_arrival_day_text": "13m",
        "avg_on_task_min": 28,
        "avg_on_task_text": "28m",
        "longest_wait_min": 25,
        "longest_wait_text": "25m",
        "avg_km": 6.2
      },
      "tasks": []
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0,
    "totals": {
      "device_type": "Totales",
      "device_type_id": null,
      "tasks_pending": 9,
      "tasks_pending_scheduled": 2,
      "tasks_in_progress": 4,
      "tasks_finished": 42,
      "tasks_cancelled": 1,
      "max_time_unassigned_min": 0,
      "max_time_unassigned_text": "",
      "avg_arrival_day_min": 17.5,
      "avg_arrival_day_text": "17m 30s",
      "avg_on_task_min": 34.5,
      "avg_on_task_text": "34m 30s",
      "longest_wait_min": 0,
      "longest_wait_text": "",
      "avg_km": 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.