Workflows

SDK reference for workflows — Inspect deployed workflows, start executions, and read run state and traces.

Inspect deployed workflows, start executions, and read run state and traces.

getWorkflowSnapshot

Get a workflow snapshot with all its nodes and edges. Each node has position: { x, y } (canvas coordinates). Use before executeWorkflow.

GET

Usage:

const result = await swirls.client.workflows.getWorkflowSnapshot({
  id: '...',
})

Input:

Parameter	Type	Required	Description
`id`	`string`	Yes

Output:

Field	Type	Description
`id`	`string`
`projectId`	`string`
`deploymentId`	`string \| null`
`workflowId`	`string`
`name`	`string`
`label`	`string`
`description`	`string \| null`
`createdAt`	`unknown`
`orgId`	`string`
`userId`	`string`
`nodes`	`object[]`
`edges`	`object[]`

listWorkflows

List one row per stable workflow with preferred snapshot, version count, and active-deployment flag.

GET

Usage:

const result = await swirls.client.workflows.listWorkflows({
  projectId: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`pagination`	`object`	No

Output:

Field	Type	Description
`pagination`	`object`
`results`	`object[]`
`totalCount`	`number`

Execute a workflow with input data. Returns an execution ID that can be used to track progress via get_execution. IMPORTANT: Before calling this tool, first call getWorkflowSnapshot with the workflow snapshot id to inspect the workflow's nodes and understand what input data is expected. The first node's inputSchema defines the required shape of the "input" object. Omitting required input fields will cause the execution to fail.

POST

Usage:

const result = await swirls.client.workflows.executeWorkflow({
  workflowId: '...',
})

Input:

Parameter	Type	Required
`workflowId`	`string`	Yes
`appName`	`string`	No
`input`	`object`	No

Output:

Field	Type	Description
`executionId`	`string`

getExecution

Get the status and results of a workflow execution, including all node executions. Use the executionId returned by execute_workflow. The response includes the overall status and each node's individual execution status and output.

GET

Usage:

const result = await swirls.client.workflows.getExecution({
  id: '...',
})

Input:

Parameter	Type	Required	Description
`id`	`string`	Yes
`appName`	`string`	No

Output:

Field	Type	Description
`id`	`string`
`parentWorkflowExecutionId`	`string \| null`
`workflowSnapshotId`	`string \| null`
`workflowId`	`string \| null`
`deploymentId`	`string \| null`
`executorType`	`string`
`executorId`	`string`
`triggerId`	`string \| null`
`triggerType`	`string \| null`
`status`	`string`
`input`	`unknown`
`output`	`unknown`
`outputFormatHints`	`object \| null`
`formattedOutput`	`unknown \| null`
`error`	`string \| null`
`startedAt`	`unknown`
`completedAt`	`unknown \| null`
`expiredAt`	`unknown \| null`
`createdAt`	`unknown`
`orgId`	`string`
`userId`	`string`
`nodeExecutions`	`object[]`

getExecutionReplay

Replay canonical execution events for a workflow run and return reducer-derived snapshot state

GET

Usage:

const result = await swirls.client.workflows.getExecutionReplay({
  id: '...',
})

Input:

Parameter	Type	Required	Description
`id`	`string`	Yes
`appName`	`string`	No

Output:

Field	Type	Description
`events`	`object[]`
`snapshot`	`object \| null`

getExecutionTrace

Load all actors and canonical events for a trace (workflow execution or agent session root)

GET

Usage:

const result = await swirls.client.workflows.getExecutionTrace({
  id: '...',
})

Input:

Parameter	Type	Required	Description
`id`	`string`	Yes

Output:

Field	Type	Description
`correlationId`	`string`
`rootActorId`	`string`
`actors`	`object[]`
`events`	`object[]`

mintActorExecutionGrant

Mint a short-lived WebSocket grant for a workflow execution Durable Object

POST

Usage:

const result = await swirls.client.workflows.mintActorExecutionGrant({
  projectId: '...',
  executionId: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`executionId`	`string`	Yes

Output:

Field	Type	Description
`actor`	`"directory" \| "project" \| "session" \| "execution"`
`grant`	`string`
`websocketUrl`	`string`
`expiresAt`	`string`
`appId`	`string`
`projectId`	`string`
`sessionId`	`string`
`threadId`	`string`
`runId`	`string`
`executionId`	`string`

listRunnableWorkflows

List workflows in a deployment with each workflow's entry node input schema and last execution. id in each row is the workflow snapshot id. Last execution aggregates by stable workflow when possible.

GET

Usage:

const result = await swirls.client.workflows.listRunnableWorkflows({
  projectId: '...',
  deploymentId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`deploymentId`	`string`	Yes
`appName`	`string`	No

Output:

Field	Type	Description
`results`	`object[]`

On this page