Execute Workflow Synchronously

Available since

v5.1.0 and later

Endpoint: POST /api/workflow/execute/{name}/{version}

Starts a workflow execution synchronously with the given consistency, which defines how reliably the request is stored and replicated before processing.

If the workflow includes a Yield task, the endpoint returns the response based on the returnStrategy. This endpoint is ideal for real-time systems that require immediate feedback or workflow chaining.

Path parameters

Parameter	Description	Type	Required/ Optional
name	The name of the workflow to be executed.	string	Required.
version	The workflow version. If unspecified, the latest version will be used.	integer	Required.

Query parameters

Parameter	Description	Type	Required/ Optional
requestId	A user-generated request ID, which can be used to track the API request.	string	Optional.
waitUntilTaskRef	The reference name of the task to wait for before returning a response. If the workflow is incomplete, the response will return 206.	string	Optional.
waitForSeconds	The duration in seconds to wait before returning a response. Default is 10.	integer	Optional.
consistency	Specifies how the request persists and is replicated. Supported values: SYNCHRONOUS—Executes the workflow directly from memory without persisting the request. This option offers the lowest latency but is non-durable. DURABLE—The request is stored in persistence before the workflow execution. This ensures reliable execution. REGION_DURABLE—The request is replicated across regions before the workflow execution. This method provides the highest level of durability and fault tolerance but may introduce additional latency. Default is DURABLE.	string	Optional.
returnStrategy	If the workflow includes a Yield task, this parameter defines the strategy for when the API returns a response. Supported values: TARGET_WORKFLOW–Returns the state of the originally triggered workflow. BLOCKING_WORKFLOW–Returns the state of the workflow that is currently blocking the execution, which may be a sub-workflow. BLOCKING_TASK–Returns the execution status of the task that is currently blocking workflow execution. BLOCKING_TASK_INPUT–Returns the input of the task that is currently blocking workflow execution. Useful for introspecting runtime behavior or debugging. Default is TARGET_WORKFLOW.	string	Optional.

Request body

Contains the workflow inputs. Format the request body as an object containing key-value pairs.

Example

{
  "someKey": “someValue”,
  "anotherKey": {}
}

Response

By default, the API returns the workflow’s current state upon synchronous execution. If a Yield task is present, the response is governed by the specified returnStrategy.

Examples

Execute a workflow synchronously

Request

curl -X 'POST' \
  'https://<YOUR-CLUSTER>/api/workflow/execute/understand_sync_async/1?waitForSeconds=5&consistency=DURABLE' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"someKey":"someValue"}'

Response

{
  "workflowId": "714b8006-5817-11f0-b9c7-fa37a82f8148",
  "input": {},
  "output": {},
  "priority": 0,
  "variables": {},
  "tasks": [
    {
      "taskType": "HTTP",
      "status": "SCHEDULED",
      "inputData": {
        "encode": true,
        "headers": {},
        "method": "GET",
        "asyncComplete": false,
        "service": "httpBinDemo",
        "_createdBy": "john.doe@acme.com",
        "body": {},
        "uri": "http://httpbin:8081/api/hello/with-delay?name=test&delaySeconds=10",
        "contentType": "application/json",
        "accept": "application/json"
      },
      "referenceTaskName": "http_ref",
      "retryCount": 0,
      "seq": 1,
      "pollCount": 0,
      "taskDefName": "http",
      "scheduledTime": 1751551815771,
      "startTime": 0,
      "endTime": 0,
      "updateTime": 0,
      "startDelayInSeconds": 0,
      "retried": false,
      "executed": false,
      "callbackFromWorker": true,
      "responseTimeoutSeconds": 0,
      "workflowInstanceId": "714b8006-5817-11f0-b9c7-fa37a82f8148",
      "workflowType": "understand_sync_async",
      "taskId": "715a2607-5817-11f0-b9c7-fa37a82f8148",
      "callbackAfterSeconds": 0,
      "outputData": {},
      "workflowTask": {
        "name": "http",
        "taskReferenceName": "http_ref",
        "inputParameters": {
          "uri": "http://httpbin:8081/api/hello/with-delay?name=test&delaySeconds=10",
          "method": "GET",
          "accept": "application/json",
          "contentType": "application/json",
          "encode": true,
          "service": "httpBinDemo",
          "body": {},
          "headers": {},
          "asyncComplete": false
        },
        "type": "HTTP",
        "decisionCases": {},
        "defaultCase": [],
        "forkTasks": [],
        "startDelay": 0,
        "joinOn": [],
        "optional": false,
        "taskDefinition": {
          "createTime": 0,
          "updateTime": 0,
          "retryCount": 3,
          "timeoutSeconds": 0,
          "inputKeys": [],
          "outputKeys": [],
          "timeoutPolicy": "TIME_OUT_WF",
          "retryLogic": "FIXED",
          "retryDelaySeconds": 60,
          "responseTimeoutSeconds": 3600,
          "inputTemplate": {},
          "rateLimitPerFrequency": 0,
          "rateLimitFrequencyInSeconds": 1,
          "backoffScaleFactor": 1,
          "totalTimeoutSeconds": 0,
          "inputSchema": {
            "createTime": 0,
            "updateTime": 0,
            "version": 1
          },
          "outputSchema": {
            "createTime": 0,
            "updateTime": 0,
            "name": "sayHelloWithDelay",
            "version": 1,
            "type": "JSON"
          },
          "enforceSchema": false
        },
        "defaultExclusiveJoinTask": [],
        "asyncComplete": false,
        "loopOver": [],
        "onStateChange": {},
        "permissive": false
      },
      "rateLimitPerFrequency": 0,
      "rateLimitFrequencyInSeconds": 0,
      "workflowPriority": 0,
      "iteration": 0,
      "subworkflowChanged": false,
      "firstStartTime": 0,
      "queueWaitTime": 0,
      "loopOverTask": false,
      "taskDefinition": {
        "createTime": 0,
        "updateTime": 0,
        "retryCount": 3,
        "timeoutSeconds": 0,
        "inputKeys": [],
        "outputKeys": [],
        "timeoutPolicy": "TIME_OUT_WF",
        "retryLogic": "FIXED",
        "retryDelaySeconds": 60,
        "responseTimeoutSeconds": 3600,
        "inputTemplate": {},
        "rateLimitPerFrequency": 0,
        "rateLimitFrequencyInSeconds": 1,
        "backoffScaleFactor": 1,
        "totalTimeoutSeconds": 0,
        "inputSchema": {
          "createTime": 0,
          "updateTime": 0,
          "version": 1
        },
        "outputSchema": {
          "createTime": 0,
          "updateTime": 0,
          "name": "sayHelloWithDelay",
          "version": 1,
          "type": "JSON"
        },
        "enforceSchema": false
      }
    }
  ],
  "createdBy": "john.doe@acme.com",
  "createTime": 1751551815675,
  "status": "RUNNING",
  "updateTime": 0
}

Execute a workflow (which contains a Yield task) synchronously

Request

curl -X 'POST' \
  'https://<YOUR-CLUSTER>/api/workflow/execute/complex_wf_signal_test_subworkflow_1/1?waitForSeconds=10&consistency=DURABLE&returnStrategy=BLOCKING_TASK' \
  -H 'accept: application/json' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"someKey":"someValue"}'

Response

{
  "responseType": "BLOCKING_TASK",
  "targetWorkflowId": "c5c86ec9-5818-11f0-8395-5666a87fdc98",
  "targetWorkflowStatus": "RUNNING",
  "workflowId": "c5c86ec9-5818-11f0-8395-5666a87fdc98",
  "input": {
    "_createdBy": "john.doe@acme.com"
  },
  "output": {},
  "taskType": "YIELD",
  "taskId": "c5d4cadb-5818-11f0-8395-5666a87fdc98",
  "referenceTaskName": "simple_ref_1",
  "retryCount": 0,
  "taskDefName": "yield",
  "workflowType": "complex_wf_signal_test_subworkflow_1",
  "priority": 0,
  "createTime": 0,
  "updateTime": 0,
  "status": "IN_PROGRESS"
}