Skip to main content

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:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour company hostname (e.g., yourcompany.geotareas.com)
Content-TypeConditionalapplication/json — required for POST and PUT requests

Query Parameters​

ParameterTypeRequiredDefaultDescription
limitintegerNo25Number of records per page. Min: 1, Max: 100
offsetintegerNo0Number of records to skip for pagination
statusstringNo—Filter by status: RUNNING, COMPLETED, CANCELLED, ERROR
definition_idstringNo—Filter by workflow definition ID. Max length: 30
entity_typestringNo—Filter by entity type
entity_idstringNo—Filter by associated entity ID. Max length: 30
startdatestringNo—Start date lower bound (ISO 8601). Max length: 30
enddatestringNo—Start date upper bound (ISO 8601). Max length: 30

Response​

FieldTypeDescription
idstringInstance unique identifier (BigInt)
definition_idstringWorkflow definition ID (BigInt)
definition_namestringWorkflow definition name
statusstring"RUNNING", "COMPLETED", "CANCELLED", or "ERROR"
entity_typestringEntity type this instance is associated with
entity_idstring | nullAssociated entity ID (BigInt)
entity_labelstring | nullAssociated entity display label
current_stepstring | nullCurrent step name (null if completed/cancelled)
started_atstringStart timestamp (ISO 8601, no timezone)
ended_atstring | nullEnd timestamp (ISO 8601, no timezone)
cancelled_atstring | nullCancellation timestamp (ISO 8601, no timezone)
pending_tasks_countintegerNumber of pending human tasks

Code Examples​

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"

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:

HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets
Retry-AfterSeconds to wait before retrying (only present on 429 responses)
X-Request-IdUnique 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​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the workflow instance (BigInt)

Response​

FieldTypeDescription
idstringInstance unique identifier (BigInt)
definition_idstringWorkflow definition ID (BigInt)
definition_namestringWorkflow definition name
statusstring"RUNNING", "COMPLETED", "CANCELLED", or "ERROR"
entity_typestringEntity type
entity_idstring | nullAssociated entity ID (BigInt)
entity_labelstring | nullAssociated entity display label
current_stepobject | nullCurrent step info (see below)
trigger_typestringHow the instance was started: manual, event, schedule
started_atstringStart timestamp
ended_atstring | nullEnd timestamp
cancelled_atstring | nullCancellation timestamp
cancelled_bystring | nullUser who cancelled the instance
cancel_reasonstring | nullReason for cancellation
tasksarrayList of tasks created for this instance (see below)

current_step object:

FieldTypeDescription
node_idstringNode identifier
namestringStep display name

tasks array items:

FieldTypeDescription
idstringTask unique identifier (BigInt)
step_namestringStep display name
statusstring"PENDING", "IN_PROGRESS", "COMPLETED"
assigned_tostring | nullAssigned user or group name
resultstring | nullCompletion result code
completed_atstring | nullCompletion 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​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the workflow instance (BigInt)

Response​

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

FieldTypeDescription
eventstringEvent type: started, step_completed, step_started, reassigned, cancelled, completed, error
datetimestringEvent timestamp (ISO 8601, no timezone)
actorstringUser or system that triggered the event
detailsobject | nullAdditional 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​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the workflow instance (BigInt)

Response​

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

FieldTypeDescription
step_namestringStep display name
completed_bystringUser who completed the step
completed_atstringCompletion timestamp (ISO 8601, no timezone)
result_codestringCompletion result code
result_labelstringHuman-readable result label
fieldsarrayList of captured field values (see below)

fields array items:

FieldTypeDescription
namestringField identifier
typestringField type: text, number, date, boolean, select, file
valueanyCaptured 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 Limit10 req/min (sliding window)

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 company hostname (e.g., yourcompany.geotareas.com)
Content-TypeConditionalapplication/json — required for POST and PUT requests

Request Body​

FieldTypeRequiredDescription
definition_idstringYesThe workflow definition ID to instantiate. Max length: 30
entity_typestringYesEntity type: TAREA, CUENTA, CLIENTE, PERSONAL, DISPOSITIVO, NINGUNA
entity_idstringNoThe entity ID to associate with this instance. Max length: 30

Code Examples​

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"
  }'

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​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the workflow instance (BigInt)

Request Body​

FieldTypeRequiredDescription
reasonstringYesReason for cancelling the workflow instance. Max length: 500

Code Examples​

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."}'

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.

CodeHTTPDescription
BAD_REQUEST400Missing required headers
VALIDATION_ERROR400Invalid params
UNAUTHORIZED401Invalid or expired JWT / API Key
FORBIDDEN403User lacks required permission
NOT_FOUND404Resource not found
RATE_LIMITED429Exceeded rate limit
INTERNAL_ERROR500Unexpected server error