Workflow executions

Run a workflow

Required capabilities: workflowOrchestrationACL:WRITE

Start an execution of a specific version of a workflow.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
workflowExternalId
required
string (WorkflowExternalId) <= 255 characters

Identifier for a workflow. Must be unique for the project. No trailing or leading whitespace and no null characters allowed.

version
required
string (Version) <= 255 characters

Identifier for a version. Must be unique for the workflow. No trailing or leading whitespace and no null characters allowed.

Request Body schema: application/json
required
required
object (Authentication)
input
object (ExecutionInput)

Input data to the workflow. The content of the input data can be used as input to the workflow tasks using references. The input data should be in JSON format, and is limited to 100KB in size.

object (metadata) <= 10 properties

Custom, application-specific metadata. String key -> String value. Keys have a maximum length of 32 characters, values a maximum of 255, and there can be a maximum of 10 key-value pairs.

Responses
202

Information about the workflow execution

post/workflows/{workflowExternalId}/versions/{version}/run
Request samples
application/json
{
  • "authentication": {
    },
  • "input": {
    },
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "059edaa4-a17a-4102-910e-2c3591500cce",
  • "workflowExternalId": "string",
  • "version": "string",
  • "status": "RUNNING",
  • "engineExecutionId": "f6159fbb-e5a2-449c-9fd5-75ed6534354c",
  • "createdTime": 1730204346000,
  • "startTime": 1730204346000,
  • "endTime": 1730204346000,
  • "reasonForIncompletion": "string",
  • "metadata": {
    }
}

Filter workflow executions

Required capabilities: workflowOrchestrationACL:READ

List workflow executions matching a given filter.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required
object (ListExecutionsFilter)
limit
integer (limit) [ 1 .. 1000 ]

The maximum number of results to return.

cursor
string (cursor)

Cursor to use for paging through results. This cursor is returned in the response of a previous request as nextCursor. If not specified, start from the first page of results.

Responses
200

Filtered list of workflow executions

post/workflows/executions/list
Request samples
application/json
{
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Retrieve workflow execution details

Required capabilities: workflowOrchestrationACL:READ

Retrieve detailed information about a specific workflow execution.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
executionId
required
string <uuid> (WorkflowExecutionId) = 36 characters

UUIDv4 identifier for a workflow execution.

Example: 059edaa4-a17a-4102-910e-2c3591500cce
Responses
200

Details of a workflow execution

get/workflows/executions/{executionId}
Request samples 
res = client.workflows.executions.retrieve_detailed("000560bc-9080-4286-b242-a27bb4819253")

res = client.workflows.executions.list()
res = client.workflows.executions.retrieve_detailed(res[0].id)
Response samples
application/json
{
  • "id": "059edaa4-a17a-4102-910e-2c3591500cce",
  • "workflowExternalId": "string",
  • "workflowDefinition": {
    },
  • "version": "string",
  • "status": "RUNNING",
  • "engineExecutionId": "f6159fbb-e5a2-449c-9fd5-75ed6534354c",
  • "executedTasks": [
    ],
  • "input": {
    },
  • "metadata": {
    },
  • "createdTime": 1730204346000,
  • "startTime": 1730204346000,
  • "endTime": 1730204346000,
  • "reasonForIncompletion": "string"
}

Cancel a workflow execution

Required capabilities: workflowOrchestrationACL:WRITE

Stops the specified execution from starting new workflow tasks and sets the workflow execution status to TERMINATED. Already running tasks will be marked as CANCELED. Note that the actions taken by the canceled tasks won't be stopped, and these need to be canceled separately if desired. For example, to cancel a running transformation, use the /transformations/cancel endpoint.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
executionId
required
string <uuid> (WorkflowExecutionId) = 36 characters

UUIDv4 identifier for a workflow execution.

Example: 059edaa4-a17a-4102-910e-2c3591500cce
Request Body schema: application/json
optional
reason
string <= 500 characters
Default: "cancelled"

Human-readable reason for the cancellation.

Responses
200

Updated workflow execution

404

The response for a failed request.

post/workflows/executions/{executionId}/cancel
Request samples
application/json
{
  • "reason": "cancelled"
}
Response samples
application/json
{
  • "id": "059edaa4-a17a-4102-910e-2c3591500cce",
  • "workflowExternalId": "string",
  • "version": "string",
  • "status": "RUNNING",
  • "engineExecutionId": "f6159fbb-e5a2-449c-9fd5-75ed6534354c",
  • "createdTime": 1730204346000,
  • "startTime": 1730204346000,
  • "endTime": 1730204346000,
  • "reasonForIncompletion": "string",
  • "metadata": {
    }
}

Retry workflow execution

Required capabilities: workflowOrchestrationACL:WRITE

This endpoint restarts a previously failed, timed out, or terminated workflow execution by retrying tasks that did not complete successfully. It aims to resume execution activity from the point(s) of failure.

Behavior of the retry operation:

  • Targeted Task Retry: Only retries tasks that have stopped in a terminal state such as CANCELED, FAILED, FAILED_WITH_TERMINAL_ERROR, and TIMED_OUT. Optional tasks are not retried.
  • Subworkflows and Dynamic Tasks: When a failure occurs within a subworkflow or as part of a dynamic task, only the individual nested tasks that failed are retried. The subworkflow or dynamic task container itself is not retried.
  • Retry Limits: Tasks that have reached or exceeded their designated retry limits will not have their retry counts reset to zero. Instead, each retry request permits these tasks a single additional retry.
Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
executionId
required
string <uuid> (WorkflowExecutionId) = 36 characters

UUIDv4 identifier for a workflow execution.

Example: 059edaa4-a17a-4102-910e-2c3591500cce
Request Body schema: application/json
required
required
object (Authentication)
Responses
200

Updated workflow execution

404

The response for a failed request.

post/workflows/executions/{executionId}/retry
Request samples
application/json
{
  • "authentication": {
    }
}
Response samples
application/json
{
  • "id": "059edaa4-a17a-4102-910e-2c3591500cce",
  • "workflowExternalId": "string",
  • "version": "string",
  • "status": "RUNNING",
  • "engineExecutionId": "f6159fbb-e5a2-449c-9fd5-75ed6534354c",
  • "createdTime": 1730204346000,
  • "startTime": 1730204346000,
  • "endTime": 1730204346000,
  • "reasonForIncompletion": "string",
  • "metadata": {
    }
}
➔ Next to Workflow triggers