Workflows

v0.1.0

Run async tasks with full lifecycle tracking — start, monitor, cancel, and wait for completion

Python

bash

pip install human-sdk

Start

Start a new async execution Enqueues a workflow execution and returns immediately with a pending AsyncExecution resource. The execution will be picked up by the orchestration layer and progressed through its lifecycle.

Parameter	Description
`request`	Execution start parameters

python

const execution = await client.workflows.start({
  workflow_id: 'wf_summarize',
  input: { text: 'Hello world' },
  timeout_ms: 60000,
});

Returns: The newly created execution in 'pending' status

Errors

ValidationError — If request payload is invalid

NotFoundError — If the specified workflow_id does not exist

Get

Get execution by ID Retrieves the current state of an async execution, including its status, progress, output, and step-level detail.

Parameter	Description
`id`	Execution ID

python

const execution = await client.workflows.get('exec_abc123');
console.log(execution.status, execution.progress);

Returns: Current execution state

Errors

NotFoundError — If execution does not exist

AuthorizationError — If not authorized to view execution

List

List executions with pagination Returns a paginated list of async executions, optionally filtered by status or originating workflow.

Parameter	Description
`filters`	Optional filters and pagination parameters

python

// First page
const page1 = await client.workflows.list({ limit: 20 });

// Next page
const page2 = await client.workflows.list({
  limit: 20,
  cursor: page1.next_cursor,
});

// With filters
const running = await client.workflows.list({
  status: 'running',
  workflow_id: 'wf_summarize',
});

Returns: Paginated list of executions

Cancel

Cancel a running execution Requests cooperative cancellation of an in-progress execution. The execution may take time to wind down; poll with get or use waitForCompletion to confirm the terminal state.

Parameter	Description
`id`	Execution ID to cancel

python

await client.workflows.cancel('exec_abc123');

Errors

NotFoundError — If execution does not exist

AuthorizationError — If not authorized to cancel execution

ConflictError — If execution is already in a terminal state

Wait For Completion

Wait for an execution to reach a terminal state Polls the execution at the specified interval until its status is 'completed', 'failed', or 'cancelled'. Throws if the timeout elapses before a terminal state is reached.

Parameter	Description
`id`	Execution ID to wait on
`options`	Polling and timeout configuration

python

const result = await client.workflows.waitForCompletion('exec_abc123', {
  poll_interval_ms: 2000,
  timeout_ms: 120000,
});

if (result.status === 'completed') {
  console.log('Output:', result.output);
} else if (result.status === 'failed') {
  console.error('Failed:', result.error);
}

Returns: The execution in its terminal state

Errors

NotFoundError — If execution does not exist

Error — If timeout elapses before execution completes

Types

python

interface ExecutionStep {
  /** Unique step identifier */
  id: string;
  /** Human-readable step name */
  name: string;
  /** Current step status */
  status: ExecutionStatus;
  /** Step input payload (workflow-defined) */
  input?: Record<string, unknown>;
  /** Step output payload (available when completed) */
  output?: Record<string, unknown>;
  /** When the step started executing */
  started_at?: Timestamp;
  /** When the step finished (completed, failed, or cancelled) */
  completed_at?: Timestamp;
  /** Error message if step failed */
  error?: string;
}

interface AsyncExecution {
  /** Unique execution identifier */
  id: string;
  /** Current execution status */
  status: ExecutionStatus;
  /** Input payload provided at execution start */
  input: Record<string, unknown>;
  /** Output payload (available when status is 'completed') */
  output?: Record<string, unknown>;
  /** Error description (available when status is 'failed') */
  error?: string;
  /** When execution began running */
  started_at: Timestamp;
  /** When execution finished (completed, failed, or cancelled) */
  completed_at?: Timestamp;
  /** Execution progress as a value between 0 and 1.  Reported by the executor; not all workflows support progress tracking. */
  progress?: number;
  /** Ordered list of execution steps for composite workflows.  Each step tracks its own status, input/output, and timing independently. */
  steps?: ExecutionStep[];
}

interface StartExecutionRequest {
  /** Workflow identifier to execute (optional if implied by context) */
  workflow_id?: string;
  /** Input payload passed to the workflow */
  input: Record<string, unknown>;
  /** Maximum wall-clock time in milliseconds before the execution is automatically cancelled. When omitted the platform default applies. */
  timeout_ms?: number;
  /** URL that will receive a POST callback when the execution reaches a terminal state (completed, failed, or cancelled). */
  callback_url?: string;
}

interface ExecutionListFilters {
  /** Filter by execution status */
  status?: ExecutionStatus;
  /** Filter by originating workflow */
  workflow_id?: string;
}