Execution Timeline Report

Chronological event log across workflow executions — each step advance, task event, gateway, and escalation with actor, step, and referenced entity.

GET/apidev/v1/reports/workflow/timeline

PermissionAPICLI_RPTWF_TIMELINE

Rate Limit10 req/min

Cache300s

Max Range92 days

Overview

Returns a flat, time-ordered stream of execution events across all workflow instances in a date range — step advances, task created/completed/reassigned/escalated, gateway evaluations, and other log entries. Each event resolves the workflow name, step name, acting user, and the business entity it references (for example TAREA #1234), so you can audit exactly what happened and when. Both active and archived instances are covered.

Results are paginated. The default page size is 25. Filter by one or more workflow definitions to scope the timeline to specific processes.

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`.
`definition_ids`	string	No	—	Comma-separated workflow definition IDs to filter by. Max 100.
`sort_by`	string	No	`timestamp`	Column to sort by. One of: `timestamp`, `instanceId`, `workflowName`, `eventType`, `actorName`.
`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:

timestamp · instanceId · workflowName · eventType · actorName

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/timeline?startdate=2026-03-01T00:00:00&enddate=2026-03-31T23:59:59&sort_dir=asc&limit=50"

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

Response

Response Fields

Each item in data represents one execution event.

Field	Type	Description
`logId`	string	Event log entry ID.
`timestamp`	string	Event date-time (ISO 8601).
`instanceId`	string	Workflow instance ID the event belongs to.
`workflowName`	string	Workflow definition name.
`stepName`	string	Step the event occurred at (`-` when the event is not tied to a step).
`eventType`	string	Event type code (e.g. `TASK_COMPLETED`, `STEP_ADVANCED`, `TASK_ESCALATED`).
`actorName`	string	Name of the user who triggered the event (`-` for system events).
`message`	string	Human-readable event message.
`entityType`	string \| null	Type of the referenced business entity (e.g. `TAREA`, `CUENTA`).
`entityId`	string \| null	ID of the referenced business entity.
`entityRef`	string	Readable reference, e.g. `TAREA #1234`; falls back to the workflow name when no entity is linked.

Example Response

{
  "success": true,
  "data": [
    {
      "logId": "9920011223344556",
      "timestamp": "2026-03-12T09:41:00",
      "instanceId": "8842001122334455",
      "workflowName": "Incident Resolution",
      "stepName": "Field Validation",
      "eventType": "TASK_COMPLETED",
      "actorName": "Carlos Martinez",
      "message": "Task completed with result OK",
      "entityType": "TAREA",
      "entityId": "1234",
      "entityRef": "TAREA #1234"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

Errors

Code	HTTP	Description
`VALIDATION_ERROR`	400	Invalid params: missing dates, invalid enum values, out-of-range pagination.
`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​