Reporte de Detalle de Instancias de Workflow

Detalle paginado de cada instancia de workflow iniciada en un rango de fechas — estado, duración, responsable y avance de tareas.

GET/apidev/v1/reports/workflow/instances

PermisoAPICLI_RPTWF_INSTANCIAS

Límite de solicitudes10 req/min

Caché300s

Rango máximo92 días

Resumen

Devuelve una fila por cada instancia de workflow creada dentro del rango de fechas, ordenada y paginada del lado del servidor. Cada fila informa el nombre de la definición de workflow, la entidad vinculada (tipo y referencia), el estado de la instancia, las marcas de tiempo de inicio y fin, la duración total, quién la inició y cuántas de sus tareas están completadas. Usá los filtros opcionales para acotar por definición de workflow, estado de la instancia, tipo de entidad o una búsqueda de texto libre sobre el nombre del workflow y la referencia de la entidad.

Solicitud

Encabezados de la solicitud

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

Parámetros de consulta

Parámetro	Tipo	Requerido	Por defecto	Descripción
`startdate`	string	Sí	—	Fecha-hora de inicio en ISO 8601 (ej. `2026-03-01T00:00:00`). Filtra por la fecha de creación de la instancia.
`enddate`	string	Sí	—	Fecha-hora de fin en ISO 8601. Rango máximo de 92 días desde `startdate`.
`definition_ids`	string	No	—	IDs de definición de workflow a incluir, separados por comas. Máximo 100.
`statuses`	string	No	—	Estados de instancia separados por comas (ej. `RUNNING,COMPLETED,ERROR,CANCELLED`). Máximo 20.
`entity_type`	string	No	—	Filtra por el tipo de entidad vinculada. Uno de: `TAREA`, `CUENTA`, `CLIENTE`, `PERSONAL`, `DISPOSITIVO`, `NINGUNA`.
`search`	string	No	—	Búsqueda de texto libre sobre el nombre del workflow y la referencia de la entidad. Largo máximo 120.
`sort_by`	string	No	`startedAt`	Columna por la cual ordenar. Una de: `startedAt`, `endedAt`, `durationSeconds`, `taskCount`, `status`, `entityType`, `workflowName`.
`sort_dir`	string	No	`desc`	Dirección de ordenamiento: `asc` o `desc`.
`limit`	integer	No	`25`	Cantidad de registros por página (`1`–`100`).
`offset`	integer	No	`0`	Cantidad de registros a omitir para la paginación.

sort_by se valida por reporte

Este reporte acepta exactamente estos valores:

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

También se aceptan tres alias heredados, que resuelven a las mismas columnas: wfinstcreatedat (= startedAt), wfinstenddat (= endedAt), wfinstestado (= status).

Cualquier otro valor devuelve 400 VALIDATION_ERROR, y el mensaje enumera los valores aceptados. Hasta el 2026-08-16 un sort_by no reconocido se ignoraba en silencio y el reporte volvía en su orden por defecto, así que una columna mal escrita parecía haber funcionado.

Ejemplos de código

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()

Respuesta

Campos de la respuesta

Campo	Tipo	Descripción
`wfinstid`	string	ID de la instancia.
`workflowName`	string	Nombre de la definición de workflow.
`entityType`	string	Tipo de entidad vinculada (ej. `TASK`, `ACCOUNT`, `NONE`).
`entityId`	string	ID de la entidad vinculada.
`entityRef`	string	Referencia legible de la entidad.
`status`	string	Estado de la instancia (ej. `RUNNING`, `COMPLETED`, `ERROR`, `CANCELLED`).
`startedAt`	string	Marca de tiempo de inicio de la instancia.
`endedAt`	string \| null	Marca de tiempo de fin de la instancia, o `null` si sigue en ejecución.
`durationSeconds`	number	Tiempo total transcurrido en segundos (hasta el fin, o hasta ahora si está en ejecución).
`startedByName`	string \| null	Nombre del usuario que inició la instancia.
`taskCount`	number	Total de tareas en la instancia.
`completedTaskCount`	number	Tareas ya completadas.

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "wfinstid": "748293048576123",
      "workflowName": "Incident Resolution",
      "entityType": "TASK",
      "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
  }
}

Errores

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Parámetros inválidos: fechas faltantes, rango > 92 días, valores de enum inválidos.
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
`FORBIDDEN`	403	El usuario no tiene el permiso requerido.
`RATE_LIMITED`	429	Se superaron las 10 req/min.
`INTERNAL_ERROR`	500	Error inesperado del servidor.

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Respuesta​

Campos de la respuesta​

Respuesta de ejemplo​

Errores​

Relacionados​