Skip to content

Start workflows

Prerequisites

  • The workflow definition is registered.
  • Every SIMPLE task has a task definition and a running worker.
  • The CLI or selected SDK is configured for the same server.

Start with the CLI

Use asynchronous start for long-running work:

conductor workflow start -w sample_workflow -i '{"service":"fedex"}'

Pin a version and attach a business correlation ID when repeatability and lookup matter:

conductor workflow start -w sample_workflow --version 2 \
  --correlation order-123 -i '{"service":"fedex"}'

For a bounded test, --sync waits for the execution result:

conductor workflow start -w sample_workflow -i '{"service":"fedex"}' --sync

Success is a returned workflow ID for an asynchronous start, or a workflow result with the expected status for a synchronous start.

Start with REST

POST /api/workflow/{name} accepts the workflow input map directly and returns the workflow ID as text.

curl -sS -X POST '<YOUR-CLUSTER-URL>/api/workflow/sample_workflow' \
  -H 'Content-Type: application/json' \
  --data '{"service":"fedex"}'

Use POST /api/workflow with a StartWorkflowRequest when you need fields such as version, correlationId, priority, or taskToDomain. Use POST /api/workflow/execute/{name}/{version} only when the caller should wait synchronously. The Start Workflow API owns the complete request and response reference.

Start with an SDK

These examples show the start call after client configuration. Use the SDK reference linked below each tab for dependency and authentication setup.

StartWorkflowRequest request = new StartWorkflowRequest();
request.setName("sample_workflow");
request.setVersion(2);
request.setCorrelationId("order-123");
request.setInput(Map.of("service", "fedex"));

String workflowId = clients.getWorkflowClient().startWorkflow(request);

See the Java SDK.

from conductor.client.http.models import StartWorkflowRequest

request = StartWorkflowRequest(
    name="sample_workflow",
    version=2,
    correlation_id="order-123",
    input={"service": "fedex"},
)
workflow_id = executor.start_workflow(request)

See the Python SDK.

const workflowId = await workflowClient.startWorkflow({
  name: "sample_workflow",
  version: 2,
  correlationId: "order-123",
  input: { service: "fedex" },
});

See the JavaScript and TypeScript SDK.

workflowID, err := workflowExecutor.StartWorkflow(&model.StartWorkflowRequest{
    Name:          "sample_workflow",
    Version:       2,
    CorrelationId: "order-123",
    Input: map[string]string{
        "service": "fedex",
    },
})
if err != nil {
    return err
}

See the Go SDK.

Inspect the execution

conductor workflow get-execution <workflow-id> -c

Confirm the workflow name and version, input, current status, and each task status. Submission alone is not proof that a worker or integration completed.

Limitations

  • Synchronous execution keeps the client waiting and is a poor fit for human tasks, timers, and long-running workers.
  • Omitting version selects the server's latest registered version; pin it when callers require repeatable behavior.
  • A correlation ID helps lookup but is not necessarily unique and is not a substitute for the workflow ID.

Next, learn how to view executions or choose an automatic trigger.