Starting Tasks

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

Installation

TypeScript

npm install @requence/task

Python

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
})

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
)

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")

Next Steps

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