Tasks

A Task is the atomic unit of work in Clockwork. Tasks belong to a WorkflowInstance, have a duration and optional deadline, and flow through a lifecycle: pending → ready → running → completed (or failed/cancelled).

The scheduling engine automatically re-computes start times, critical path, and conflicts after every task mutation.

When to use `client.tasks`

Creating tasks dynamically as your system processes new work items
Building a human task inbox that polls for ready tasks assigned to a user
Completing or delaying tasks from a webhook handler or automation script
Monitoring task slack (slackSec) to identify scheduling risk

Methods

Method	Description
`create(input)`	Add a task to a workflow instance
`get(taskId)`	Fetch a task with computed schedule fields
`list(opts?)`	List tasks filtered by instance or status
`update(taskId, input)`	Update name, duration, status, dates, tags, priority
`delete(taskId)`	Delete task; downstream tasks reschedule automatically
`complete(taskId)`	Mark done; returns newly unlocked downstream tasks
`assign(taskId, userId)`	Assign to a platform user
`assignResource(taskId, resourceId)`	Assign a resource (equipment, agent, service)
`delay(taskId, input)`	Delay by minutes or to a new earliest start; slip propagates downstream

`tasks.create(input)`

Parameters

Parameter	Type	Required	Description
`name`	`string`	yes	Human-readable task name
`workflowInstanceId`	`string`	no	Bind to a running workflow instance
`durationMinutes`	`number`	no	Estimated duration in minutes
`durationSeconds`	`number`	no	Fine-grained duration override
`earliestStart`	`string`	no	ISO 8601 — defaults to now
`deadline`	`string`	no	ISO 8601 hard deadline
`isFixed`	`boolean`	no	If `true`, start time never moves regardless of dependencies
`priority`	`'high' \| 'medium' \| 'low'`	no	Display priority (does not affect scheduling)
`assigneePlatformUserId`	`string`	no	Assign on creation
`tags`	`string[]`	no	Freeform labels
`bufferAfterMinutes`	`number`	no	Cooldown time after the task finishes
`subjectType`	`string`	no	Opaque label for external entity type (e.g., `'customer'`)
`subjectId`	`string`	no	External entity ID

Returns

Promise<ApiResponse<Task>> — data is the created Task.

Example

typescript

import { Clockwork } from '@clockwork/sdk'
 
const client = new Clockwork({ apiKey: process.env.CLOCKWORK_API_KEY })
 
const { data: task } = await client.tasks.create({
  name: 'Review contract draft',
  workflowInstanceId: 'wi_abc123',
  durationMinutes: 30,
  priority: 'high',
  deadline: '2026-07-01T17:00:00Z',
  tags: ['legal', 'q3'],
})
 
console.log(task.id, task.status) // tsk_... 'pending'

`tasks.get(taskId)`

Fetches a single task including engine-computed fields (slackSec, isCritical).

typescript

const { data: task } = await client.tasks.get('tsk_abc123')
 
console.log(task.slackSec)   // seconds before the critical-path deadline
console.log(task.isCritical) // true if on the critical path

`tasks.list(opts?)`

Options

Option	Type	Description
`workflowInstanceId`	`string`	Filter to one instance
`status`	`TaskStatus`	Filter by status

typescript

const { data: tasks } = await client.tasks.list({
  workflowInstanceId: 'wi_abc123',
  status: 'ready',
})

`tasks.update(taskId, input)`

Updates any mutable task field. All fields are optional.

typescript

await client.tasks.update('tsk_abc123', {
  name: 'Review final contract',
  durationMinutes: 45,
  deadline: '2026-07-02T12:00:00Z',
  priority: 'high',
})

`tasks.complete(taskId)`

Marks a task as completed. Downstream tasks that were waiting on this one become ready and are returned in unlockedTasks.

typescript

const { data } = await client.tasks.complete('tsk_abc123')
 
console.log(data.task.status) // 'completed'
console.log(data.unlockedTasks) // [{ id: '...', name: 'Send confirmation email' }]

`tasks.assign(taskId, userId)`

Assigns a task to a platform user (user must exist in your Clockwork account).

typescript

await client.tasks.assign('tsk_abc123', 'user_xyz')

`tasks.assignResource(taskId, resourceId)`

Assigns a non-user resource (equipment, AI agent, service) to the task. See Resources.

typescript

await client.tasks.assignResource('tsk_abc123', 'res_xyz')

`tasks.delay(taskId, input)`

Delays a task. The slip propagates automatically to all downstream tasks.

Parameters

Parameter	Type	Description
`delayMinutes`	`number`	Push back by this many minutes
`newEarliestStart`	`string`	ISO 8601 — set an absolute new start time
`reason`	`string`	Optional note recorded in the event log

typescript

await client.tasks.delay('tsk_abc123', {
  delayMinutes: 60,
  reason: 'Waiting on legal review',
})

`tasks.delete(taskId)`

Permanently deletes a task. Dependent tasks are disconnected and rescheduled.

typescript

await client.tasks.delete('tsk_abc123')

Task type reference

typescript

type TaskStatus = 'pending' | 'ready' | 'running' | 'blocked' | 'cancelled' | 'completed' | 'failed'
type TaskPriority = 'high' | 'medium' | 'low'
 
interface Task {
  id: string
  name: string
  description: string | null
  status: TaskStatus
  priority: TaskPriority | null
  earliestStart: string        // ISO 8601
  deadline: string | null
  durationMinutes: number
  bufferAfterMinutes: number
  isFixed: boolean
  slackSec: number | null      // Engine-computed: float before deadline breach
  isCritical: boolean | null   // Engine-computed: on the critical path?
  workflowInstanceId: string | null
  assigneePlatformUserId: string | null
  resourceIds: string[]
  tags: string[]
  subjectType: string | null
  subjectId: string | null
  createdAt: string
  updatedAt: string
}

Workflow Instances — tasks belong to instances
Dependencies — model finish-to-start ordering between tasks
Approvals — require human sign-off before a task can complete
Conflicts — detect deadline violations and resource contention