Workflow Instances Detail Report

Paginated detail of every workflow instance started in a date range — status, duration, owner, and task progress.

GET/apidev/v1/reports/workflow/instances

PermissionAPICLI_RPTWF_INSTANCIAS

Rate Limit10 req/min

Cache300s

Max Range92 days

Overview

Returns one row per workflow instance created within the date range, ordered and paginated server-side. Each row reports the workflow definition name, the linked entity (type and reference), the instance status, start/end timestamps, total duration, who started it, and how many of its tasks are completed. Use the optional filters to narrow by workflow definition, instance status, entity type, or a free-text search over the workflow name and entity reference.

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`). Filters by instance creation date.
`enddate`	string	Yes	—	ISO 8601 end date-time. Max range 92 days from `startdate`.
`definition_ids`	string	No	—	Comma-separated workflow definition IDs to include. Max 100.
`statuses`	string	No	—	Comma-separated instance statuses (e.g. `RUNNING,COMPLETED,ERROR,CANCELLED`). Max 20.
`entity_type`	string	No	—	Filter by the linked entity type. One of: `TAREA`, `CUENTA`, `CLIENTE`, `PERSONAL`, `DISPOSITIVO`, `NINGUNA`.
`search`	string	No	—	Free-text search over workflow name and entity reference. Max length 120.
`sort_by`	string	No	`startedAt`	Column to sort by. One of: `startedAt`, `endedAt`, `durationSeconds`, `taskCount`, `status`, `entityType`, `workflowName`.
`sort_dir`	string	No	`desc`	Sort direction: `asc` or `desc`.
`limit`	integer	No	`25`	Number of records per page (`1`–`100`).
`offset`	integer	No	`0`	Number of records to skip for pagination.

sort_by is validated per report

This report accepts exactly these values:

startedAt · endedAt · durationSeconds · taskCount · status · entityType · workflowName

Three legacy aliases are also accepted and resolve to the same columns: wfinstcreatedat (= startedAt), wfinstenddat (= endedAt), wfinstestado (= status).

Anything else returns 400 VALIDATION_ERROR, and the message names the accepted values. Until 2026-08-16 an unrecognised sort_by was silently ignored and the report came back in its default order, so a mis-typed column looked like it had worked.

Code Examples

cURL
JavaScript
Python

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

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

Response

Response Fields

Field	Type	Description
`wfinstid`	string	Instance ID.
`workflowName`	string	Workflow definition name.
`entityType`	string	Linked entity type (`TAREA`, `CUENTA`, `CLIENTE`, `PERSONAL`, `DISPOSITIVO`, `NINGUNA`).
`entityId`	string	Linked entity ID.
`entityRef`	string	Human-readable entity reference.
`status`	string	Instance status (e.g. `RUNNING`, `COMPLETED`, `ERROR`, `CANCELLED`).
`startedAt`	string	Instance start timestamp.
`endedAt`	string \| null	Instance end timestamp, or `null` if still running.
`durationSeconds`	number	Total elapsed time in seconds (to end, or to now if running).
`startedByName`	string \| null	Name of the user who started the instance.
`taskCount`	number	Total tasks in the instance.
`completedTaskCount`	number	Tasks already completed.

Example Response

{
  "success": true,
  "data": [
    {
      "wfinstid": "748293048576123",
      "workflowName": "Incident Resolution",
      "entityType": "TAREA",
      "entityId": "552398174620055",
      "entityRef": "552398174620055",
      "status": "COMPLETED",
      "startedAt": "2026-03-04T09:12:00",
      "endedAt": "2026-03-04T11:48:00",
      "durationSeconds": 9360,
      "startedByName": "Carlos Martinez",
      "taskCount": 5,
      "completedTaskCount": 5
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Errors

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