Workflow Instances

A Workflow Instance is a live execution of a workflow — a collection of tasks running toward completion. Instances can be created from a template (inheriting its structure) or built up programmatically by adding tasks and dependencies directly.

When to use `client.workflowInstances`

Launching a new workflow when a business event occurs (deal signed, customer created, order placed)
Monitoring overall workflow status (running, blocked, completed)
Filtering instances by subject to find all workflows associated with a specific customer or project
Cancelling a workflow when the underlying business event is voided

Methods

Method	Description
`create(input)`	Launch a new instance (optionally from a template)
`get(instanceId)`	Fetch instance and current status
`cancel(instanceId)`	Cancel instance and all open tasks
`list(opts?)`	List instances filtered by project, status, or subject

`workflowInstances.create(input)`

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	no	Instantiate from a published template
`projectId`	`string`	no	Defaults to personal project
`subjectType`	`string`	no	Opaque label for the triggering entity (e.g., `'customer'`)
`subjectId`	`string`	no	ID of the triggering entity
`metadata`	`Record<string, unknown>`	no	Arbitrary key-value data

Example

typescript

// Create from a template
const { data: instance } = await client.workflowInstances.create({
  templateId: 'tmpl_abc123',
  subjectType: 'customer',
  subjectId: 'cust_xyz',
})
 
console.log(instance.id, instance.status) // wi_... 'pending'

typescript

// Create standalone (no template)
const { data: instance } = await client.workflowInstances.create({
  subjectType: 'deal',
  subjectId: 'deal_987',
  metadata: { region: 'us-west', tier: 'enterprise' },
})

`workflowInstances.get(instanceId)`

typescript

const { data: instance } = await client.workflowInstances.get('wi_abc123')
console.log(instance.status)      // 'running'
console.log(instance.completedAt) // null (still running)

`workflowInstances.list(opts?)`

Options

Option	Type	Description
`projectId`	`string`	Filter by project
`status`	`WorkflowInstanceStatus`	Filter by status
`subjectId`	`string`	Find all instances for a specific subject

typescript

// Find all running onboarding workflows for a customer
const { data: instances } = await client.workflowInstances.list({
  subjectId: 'cust_xyz',
  status: 'running',
})

`workflowInstances.cancel(instanceId)`

Cancels the instance and marks all open tasks as cancelled. This cannot be undone.

typescript

const { data: instance } = await client.workflowInstances.cancel('wi_abc123')
console.log(instance.status) // 'cancelled'

Instance status lifecycle

pending → running → completed
                  ↘ failed
                  ↘ cancelled
                  ↘ blocked   (all open tasks are blocked)

Type reference

typescript

type WorkflowInstanceStatus = 'pending' | 'running' | 'blocked' | 'completed' | 'failed' | 'cancelled'
 
interface WorkflowInstance {
  id: string
  templateId: string | null
  projectId: string
  status: WorkflowInstanceStatus
  startedAt: string | null
  completedAt: string | null
  subjectType: string | null
  subjectId: string | null
  metadata: Record<string, unknown> | null
  createdAt: string
  updatedAt: string
}

Workflow Templates — define reusable blueprints
Tasks — add tasks to an instance
Roles — fill role slots after instantiating a template
Events — stream real-time lifecycle events