Starting Tasks

Once a task template is planned in the UI and services are implemented, you can start tasks programmatically.

Installation

TypeScript

bash npm install @requence/task

Python

bash pip install requence

Basic Usage

TypeScript

import { createTask } from '@requence/task'

const result = await createTask({
  taskTemplate: 'my-template',
  input: { name: 'World' },
})

console.log(result.result) // The final output of the task

Caution

await createTask(...) waits for the entire task to finish. If you don’t need to block, omit the await and use the returned task handle instead.

Python

from requence.task import Task

task = Task(
    task_template="my-template",
    input={"name": "World"},
)

result = task.sync.result  # Blocks until the task completes
print(result.result)       # The final output of the task

Task Handle

createTask / Task returns a task handle with methods to access task metadata without waiting for the task to finish:

TypeScript

const task = createTask({ taskTemplate: 'my-template', input: {} })

const taskId = await task.getTaskId()   // Resolves as soon as the task is created
const taskUrl = await task.getTaskUrl() // URL to view the task in the Requence UI
await task.abort('No longer needed')    // Abort the running task
await task.protect()                    // Protect the task from auto cleanup

// Await the final result only when needed
const result = await task

The task handle is also an AsyncIterable — see Streaming Updates.

Python

task = Task(task_template="my-template", input={})

# Synchronous access
task_id = task.sync.id       # Blocks until the task is created
task_url = task.sync.url     # URL to view the task in the Requence UI
task.abort("No longer needed")
task.protect()               # Protect the task from auto cleanup

# Async access
task_id = await task.task_id
task_url = await task.task_url
result = await task.result

Awaiting Finalization / Validation (Cheap Monitoring)

By default, awaiting the task handle (await task / await task.result) or using onUpdate will start active task monitoring. Active monitoring connects to the Server-Sent Events (SSE) stream to track the progress of every node, which is expensive and often unnecessary if you only want to start the task and catch initial validation errors.

If you want to ensure the task has successfully passed input schema validation and successfully started on the backend—without incurring the overhead of monitoring the entire execution—you can await task.finalized():

TypeScript

const task = createTask({
  taskTemplate: 'my-template',
  input: { /* ... */ },
})

try {
  // Resolves when input validation passes and the task starts on the backend.
  // Rejects immediately with a TaskError if validation fails.
  const taskId = await task.finalized()
  console.log(`Task ${taskId} is running in the background!`)
} catch (error) {
  console.error('Validation failed:', error.message)
}

Python

task = Task(task_template="my-template", input={})

# Async
try:
    task_id = await task.finalized()
    print(f"Task {task_id} is running in the background!")
except TaskException as error:
    print("Validation failed:", error.message)

# Synchronous
try:
    task_id = task.sync.finalized()
    print(f"Task {task_id} is running in the background!")
except TaskException as error:
    print("Validation failed:", error.message)

Options

TypeScript

const result = await createTask({
  taskTemplate: 'my-template',   // Required — name of the task template
  input: { /* ... */ },           // Required if the template defines an input schema
  name: 'Daily Import',          // Optional — human-readable task name
  priority: 5,                   // Optional — 0 (low) to 10 (high), default: 5
  requireAck: true,              // Optional — see Delivery Guarantee below
})

Python

task = Task(
    task_template="my-template",   # Required — name of the task template
    input={"key": "value"},        # Required if the template defines an input schema
    name="Daily Import",            # Optional — human-readable task name
    priority=5,                    # Optional — 0 (low) to 10 (high), default: 5
    require_ack=True,              # Optional — see Delivery Guarantee below
)

Result

The resolved result contains:

TypeScript

{
  input: unknown         // The input you provided
  result: unknown        // The final task output
  taskId: string         // Unique task identifier
  taskUrl: string        // URL to view the task in the Requence UI
  getNodeData(alias)     // Get output from a specific node by alias
  getNodeError(alias)    // Get error from a specific node by alias
}

Python

result.input          # The input you provided
result.result         # The final task output
result.task_id        # Unique task identifier
result.task_url       # URL to view the task in the Requence UI
result.get_node_data(alias)   # Get output from a specific node by alias
result.get_node_error(alias)  # Get error from a specific node by alias

Aborting a Task

TypeScript

const task = createTask({ taskTemplate: 'my-template', input: {} })

// Abort after some condition
await task.abort('No longer needed')

Or use the standalone abortTask function:

import { abortTask } from '@requence/task'

await abortTask({
  taskId: 'some-task-id',
  reason: 'Cancelled by user',
})

Python

task = Task(task_template="my-template", input={})

# Abort after some condition
task.abort("No longer needed")

Or use the standalone abort_task function:

from requence.task import abort_task

abort_task(task_id="some-task-id", reason="Cancelled by user")

Protecting a Task

Protected tasks are excluded from automatic cleanup. This is useful for important task results you want to keep indefinitely.

TypeScript

const task = createTask({ taskTemplate: 'my-template', input: {} })

// Protect after the task is created
await task.protect()

Or use the standalone protectTask function:

import { protectTask } from '@requence/task'

await protectTask({
  taskId: 'some-task-id',
})

Python

task = Task(task_template="my-template", input={})

# Protect after the task is created
task.protect()

Or use the standalone protect_task function:

from requence.task import protect_task

protect_task(task_id="some-task-id")

Delivery Guarantee

By default a task transitions directly from RUNNING to SUCCESSFUL / FAILED / STOPPED when it finishes. If the process that started the task crashes or disconnects at the exact moment the terminal event is emitted, the event can be lost.

Setting requireAck: true (require_ack=True in Python) enables an explicit acknowledgement step:

1. When the task reaches its terminal state the backend holds it in AWAITING_DELIVERY instead of immediately finalising it.
2. The SDK receives the terminal event over the SSE stream and automatically sends an ACK back to the backend.
3. Only after the ACK is received does the task move to its real final status (SUCCESSFUL, FAILED, or STOPPED), and the exact delivery timestamp is recorded.

Because the ACK is tied to the same access token that created the task, the backend can guarantee the correct client received the result.

Note

The task remains in AWAITING_DELIVERY indefinitely until the SDK connects and ACKs. The Requence UI shows a distinct awaiting delivery indicator (✉️) while the task is in this state, and a delivered timestamp once the ACK is confirmed (✅).

TypeScript

// The SDK handles the ACK automatically — await the result as normal.
const result = await createTask({
  taskTemplate: 'my-template',
  input: { /* ... */ },
  requireAck: true,
})

console.log(result.result) // Only resolves after the ACK has been confirmed

Python

task = Task(
    task_template="my-template",
    input={},
    require_ack=True,
)

result = task.sync.result  # Only resolves after the ACK has been confirmed

requireAck also works with watchTasks / TaskWatcher — when a task with requireAck reaches its terminal state, the watcher automatically sends the ACK on behalf of the access token that created the task.

Next Steps

Learn about Streaming Updates to monitor task progress in real-time.