Workflow Instances

Start, cancel, and monitor workflow executions. Retrieve instance details with tasks, event timelines, and captured form data across all completed steps.

Prerequisites

All endpoints on this page require a valid JWT token, API key, and tenant header. See Authentication for details.

List Instances

Retrieve a paginated list of workflow instances.

GET/apidev/v1/workflow/instances

PermissionAPICLI_WORKFLOW_READ

Rate Limit30 req/min (sliding window)

Cache15s

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
`limit`	integer	No	`25`	Number of records per page. Min: `1`, Max: `100`
`offset`	integer	No	`0`	Number of records to skip for pagination
`status`	string	No	—	Filter by status: `RUNNING`, `COMPLETED`, `CANCELLED`, `ERROR`
`definition_id`	string	No	—	Filter by workflow definition ID. Max length: 30
`entity_type`	string	No	—	Filter by entity type
`entity_id`	string	No	—	Filter by associated entity ID. Max length: 30
`startdate`	string	No	—	Start date lower bound (ISO 8601). Max length: 30
`enddate`	string	No	—	Start date upper bound (ISO 8601). Max length: 30

Response

Field	Type	Description
`id`	string	Instance unique identifier (BigInt)
`definition_id`	string	Workflow definition ID (BigInt)
`definition_name`	string	Workflow definition name
`status`	string	`"RUNNING"`, `"COMPLETED"`, `"CANCELLED"`, or `"ERROR"`
`entity_type`	string	Entity type this instance is associated with
`entity_id`	string \| null	Associated entity ID (BigInt)
`entity_label`	string \| null	Associated entity display label
`current_step`	string \| null	Current step name (null if completed/cancelled)
`started_at`	string	Start timestamp (ISO 8601, no timezone)
`ended_at`	string \| null	End timestamp (ISO 8601, no timezone)
`cancelled_at`	string \| null	Cancellation timestamp (ISO 8601, no timezone)
`pending_tasks_count`	integer	Number of pending human tasks

Code Examples

cURL
JavaScript
Python

curl -s -X GET "https://$TENANT_HOST/apidev/v1/workflow/instances?limit=10&status=RUNNING" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/instances?limit=10&status=RUNNING`,
  {
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
    },
  }
);

const { data, meta } = await response.json();
console.log(`Fetched ${data.length} of ${meta.total} instances`);

import requests

response = requests.get(
    f"https://{TENANT_HOST}/apidev/v1/workflow/instances",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
    },
    params={"limit": 10, "status": "RUNNING"},
)

result = response.json()
for instance in result["data"]:
    print(f"{instance['id']}: {instance['definition_name']} ({instance['status']})")

Example Response

{
  "success": true,
  "data": [
    {
      "id": "591847302948571634",
      "definition_id": "482938470192837465",
      "definition_name": "New Account Onboarding",
      "status": "RUNNING",
      "entity_type": "CUENTA",
      "entity_id": "738291047382910473",
      "entity_label": "Acme Corp",
      "current_step": "Send Welcome Email",
      "started_at": "2026-03-15T10:00:00",
      "ended_at": null,
      "cancelled_at": null,
      "pending_tasks_count": 1
    }
  ],
  "meta": {
    "total": 34,
    "limit": 10,
    "offset": 0
  }
}

Rate Limit Headers

Every response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current window resets
`Retry-After`	Seconds to wait before retrying (only present on `429` responses)
`X-Request-Id`	Unique request identifier for debugging and support tickets

Instance Detail

Retrieve the full profile for a single workflow instance, including its associated tasks.

GET/apidev/v1/workflow/instances/{id}

PermissionAPICLI_WORKFLOW_READ

Rate Limit30 req/min (sliding window)

Cache15s

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the workflow instance (BigInt)

Response

Field	Type	Description
`id`	string	Instance unique identifier (BigInt)
`definition_id`	string	Workflow definition ID (BigInt)
`definition_name`	string	Workflow definition name
`status`	string	`"RUNNING"`, `"COMPLETED"`, `"CANCELLED"`, or `"ERROR"`
`entity_type`	string	Entity type
`entity_id`	string \| null	Associated entity ID (BigInt)
`entity_label`	string \| null	Associated entity display label
`current_step`	object \| null	Current step info (see below)
`trigger_type`	string	How the instance was started: `manual`, `event`, `schedule`
`started_at`	string	Start timestamp
`ended_at`	string \| null	End timestamp
`cancelled_at`	string \| null	Cancellation timestamp
`cancelled_by`	string \| null	User who cancelled the instance
`cancel_reason`	string \| null	Reason for cancellation
`tasks`	array	List of tasks created for this instance (see below)

current_step object:

Field	Type	Description
`node_id`	string	Node identifier
`name`	string	Step display name

tasks array items:

Field	Type	Description
`id`	string	Task unique identifier (BigInt)
`step_name`	string	Step display name
`status`	string	`"PENDING"`, `"IN_PROGRESS"`, `"COMPLETED"`
`assigned_to`	string \| null	Assigned user or group name
`result`	string \| null	Completion result code
`completed_at`	string \| null	Completion timestamp

Example Response

{
  "success": true,
  "data": {
    "id": "591847302948571634",
    "definition_id": "482938470192837465",
    "definition_name": "New Account Onboarding",
    "status": "RUNNING",
    "entity_type": "CUENTA",
    "entity_id": "738291047382910473",
    "entity_label": "Acme Corp",
    "current_step": {
      "node_id": "node_d4e5f6",
      "name": "Send Welcome Email"
    },
    "trigger_type": "manual",
    "started_at": "2026-03-15T10:00:00",
    "ended_at": null,
    "cancelled_at": null,
    "cancelled_by": null,
    "cancel_reason": null,
    "tasks": [
      {
        "id": "674839201748392017",
        "step_name": "Verify Contact Information",
        "status": "COMPLETED",
        "assigned_to": "jdoe",
        "result": "approved",
        "completed_at": "2026-03-15T11:30:00"
      },
      {
        "id": "674839201748392018",
        "step_name": "Send Welcome Email",
        "status": "IN_PROGRESS",
        "assigned_to": "Sales Team",
        "result": null,
        "completed_at": null
      }
    ]
  },
  "meta": {}
}

Instance Timeline

Retrieve the chronological event log for a workflow instance.

GET/apidev/v1/workflow/instances/{id}/timeline

PermissionAPICLI_WORKFLOW_READ

Rate Limit30 req/min (sliding window)

Cache15s

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the workflow instance (BigInt)

Response

Returns an array of timeline event objects inside the data field.

Field	Type	Description
`event`	string	Event type: `started`, `step_completed`, `step_started`, `reassigned`, `cancelled`, `completed`, `error`
`datetime`	string	Event timestamp (ISO 8601, no timezone)
`actor`	string	User or system that triggered the event
`details`	object \| null	Additional event-specific data

Example Response

{
  "success": true,
  "data": [
    {
      "event": "started",
      "datetime": "2026-03-15T10:00:00",
      "actor": "jdoe",
      "details": null
    },
    {
      "event": "step_started",
      "datetime": "2026-03-15T10:00:01",
      "actor": "system",
      "details": {"step_name": "Verify Contact Information", "assigned_to": "jdoe"}
    },
    {
      "event": "step_completed",
      "datetime": "2026-03-15T11:30:00",
      "actor": "jdoe",
      "details": {"step_name": "Verify Contact Information", "result_code": "approved"}
    }
  ],
  "meta": {}
}

Instance Captured Data

Retrieve all form data captured during the execution of a workflow instance across all completed steps.

GET/apidev/v1/workflow/instances/{id}/captured-data

PermissionAPICLI_WORKFLOW_READ

Rate Limit30 req/min (sliding window)

Cache15s

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the workflow instance (BigInt)

Response

Returns an array of captured data entries grouped by step inside the data field.

Field	Type	Description
`step_name`	string	Step display name
`completed_by`	string	User who completed the step
`completed_at`	string	Completion timestamp (ISO 8601, no timezone)
`result_code`	string	Completion result code
`result_label`	string	Human-readable result label
`fields`	array	List of captured field values (see below)

fields array items:

Field	Type	Description
`name`	string	Field identifier
`type`	string	Field type: `text`, `number`, `date`, `boolean`, `select`, `file`
`value`	any	Captured value

Example Response

{
  "success": true,
  "data": [
    {
      "step_name": "Verify Contact Information",
      "completed_by": "jdoe",
      "completed_at": "2026-03-15T11:30:00",
      "result_code": "approved",
      "result_label": "Approved",
      "fields": [
        {
          "name": "contact_verified",
          "type": "boolean",
          "value": true
        },
        {
          "name": "phone_confirmed",
          "type": "boolean",
          "value": true
        },
        {
          "name": "verification_notes",
          "type": "text",
          "value": "Confirmed via phone call."
        }
      ]
    }
  ],
  "meta": {}
}

Start Instance

Start a new workflow instance from a given definition.

POST/apidev/v1/workflow/instances

PermissionAPICLI_WORKFLOW_EXECUTE

Rate Limit30 req/min (sliding window)

note

Starting an instance shares the same rate limit bucket as the read endpoints (30 requests per minute), even though it requires the execute permission.

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

Request Body

Field	Type	Required	Description
`definition_id`	string	Yes	The workflow definition ID to instantiate. Max length: 30
`entity_type`	string	Yes	Entity type: `TAREA`, `CUENTA`, `CLIENTE`, `PERSONAL`, `DISPOSITIVO`, `NINGUNA`
`entity_id`	string	No	The entity ID to associate with this instance. Max length: 30

note

entity_id is required whenever entity_type is anything other than NINGUNA. Sending an instance with an entity type but no entity ID returns a 400 VALIDATION_ERROR.

Code Examples

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/instances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "definition_id": "482938470192837465",
    "entity_type": "CUENTA",
    "entity_id": "738291047382910473"
  }'

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/instances`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      definition_id: "482938470192837465",
      entity_type: "CUENTA",
      entity_id: "738291047382910473",
    }),
  }
);

const { data } = await response.json();
console.log(`Instance created: ${data.instance_id}`);

import requests

response = requests.post(
    f"https://{TENANT_HOST}/apidev/v1/workflow/instances",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
        "Content-Type": "application/json",
    },
    json={
        "definition_id": "482938470192837465",
        "entity_type": "CUENTA",
        "entity_id": "738291047382910473",
    },
)

result = response.json()
print(f"Instance created: {result['data']['instance_id']}")

Example Response (201 Created)

{
  "success": true,
  "data": {
    "instance_id": "591847302948571635",
    "status": "RUNNING",
    "current_step": "Verify Contact Information"
  },
  "meta": {}
}

Cancel Instance

Cancel a running workflow instance. The instance status changes to CANCELLED and all pending tasks are closed.

POST/apidev/v1/workflow/instances/{id}/cancel

PermissionAPICLI_WORKFLOW_EXECUTE

Rate Limit10 req/min (sliding window)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the workflow instance (BigInt)

Request Body

Field	Type	Required	Description
`reason`	string	Yes	Reason for cancelling the workflow instance. Max length: 500

Code Examples

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/instances/591847302948571634/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Account onboarding no longer needed — duplicate."}'

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/instances/591847302948571634/cancel`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reason: "Account onboarding no longer needed — duplicate.",
    }),
  }
);

const { data } = await response.json();
console.log(`Instance ${data.instance_id} cancelled`);

import requests

response = requests.post(
    f"https://{TENANT_HOST}/apidev/v1/workflow/instances/591847302948571634/cancel",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
        "Content-Type": "application/json",
    },
    json={"reason": "Account onboarding no longer needed — duplicate."},
)

result = response.json()
print(f"Instance {result['data']['instance_id']} cancelled")

Example Response

{
  "success": true,
  "data": {
    "instance_id": "591847302948571634",
    "status": "CANCELLED",
    "cancelled_at": "2026-03-19T14:05:00"
  },
  "meta": {}
}

Errors

All endpoints on this page may return the following errors. For the full error reference, see Error Handling.

Code	HTTP	Description
`VALIDATION_ERROR`	400	Invalid params
`UNAUTHORIZED`	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
`FORBIDDEN`	403	User lacks required permission
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Exceeded rate limit
`INTERNAL_ERROR`	500	Unexpected server error

Authentication -- How to obtain and use JWT tokens and API keys
Workflow Definitions -- Browse available workflow blueprints
Workflow Tasks -- Complete and reassign workflow tasks
Pagination -- Standard pagination parameters and metadata
Rate Limits -- Rate limit windows and retry strategies
Error Handling -- Full error codes reference

List Instances​

Request Headers​

Query Parameters​

Response​

Code Examples​

Example Response​

Rate Limit Headers​

Instance Detail​

Path Parameters​

Response​

Example Response​

Instance Timeline​

Path Parameters​

Response​

Example Response​

Instance Captured Data​

Path Parameters​

Response​

Example Response​

Start Instance​

Request Headers​

Request Body​

Code Examples​

Example Response (201 Created)​

Cancel Instance​

Path Parameters​

Request Body​

Code Examples​

Example Response​

Errors​

Related Resources​

List Instances

Request Headers

Query Parameters

Response

Code Examples

Example Response

Rate Limit Headers

Instance Detail

Path Parameters

Response

Example Response

Instance Timeline

Path Parameters

Response

Example Response

Instance Captured Data

Path Parameters

Response

Example Response

Start Instance

Request Headers

Request Body

Code Examples

Example Response (201 Created)

Cancel Instance

Path Parameters

Request Body

Code Examples

Example Response

Errors

Related Resources