Tasks

Submit asynchronous agent jobs, track their progress, and retrieve results. Tasks are the async alternative to agent.run() — submit a job, get a task ID, and poll or wait for completion.

How tasks work

When you call session.run() or agent.run(), the call blocks until the agent completes. Tasks let you decouple submission from completion:

Submit a task with an agent and input
Get back a taskId immediately
Poll with tasks.get() or block with tasks.wait()
Optionally receive a webhook when the task completes

Submitting a task

submit-task.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })
const session = await theazo.sessions.forUser(class="cb-str">'user_123')

// Submit a task — returns immediately
const task = await session.tasks.submit({
  agent: class="cb-str">'researcher',
  input: { query: class="cb-str">'analyze competitor pricing for Q2 2025' },
  priority: class="cb-str">'high',
})

console.log(task.taskId)  class="cb-cmt">// 'task_abc123'
console.log(task.status)  class="cb-cmt">// 'queued'

Tasks are scoped to a session. Each task runs an agent within that session's isolation boundary, limits, and billing context.

Checking task status

Polling

poll-task.ts

const task = await session.tasks.get(class="cb-str">'task_abc123')

console.log(task.status)    class="cb-cmt">// 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
console.log(task.progress)  class="cb-cmt">// 0.65 (65% complete, if agent reports progress)
console.log(task.message)   class="cb-cmt">// 'Processing 45 of 200 items...'

if (task.status === class="cb-str">'completed') {
  console.log(task.output)  class="cb-cmt">// Agent's final output
  console.log(task.cost)    class="cb-cmt">// { amount: 234, currency: 'usd' }
}

Waiting (long poll)

Use tasks.wait() to block until the task completes or a timeout is reached. The server holds the connection open — no client-side polling loop needed.

wait-task.ts

// Block until completed or 5 minutes, whichever comes first
const result = await session.tasks.wait(class="cb-str">'task_abc123', {
  timeout: class="cb-str">'5m',
})

if (result.status === class="cb-str">'completed') {
  console.log(result.output)
} else {
  console.log(class="cb-str">'Task still running after timeout')
}

Webhook notification

Pass a webhook URL when submitting the task. Theazo will POST the completed task payload to your endpoint.

const task = await session.tasks.submit({
  agent: class="cb-str">'data_processor',
  input: { dataset: class="cb-str">'customers_q2.csv' },
  webhook: class="cb-str">'https://your-api.com/webhooks/task-complete'bhooks/task-complete',
})
// When the task completes, Theazo POSTs:
// { taskId: 'task_abc', status: 'completed', output: '...', cost: { amount: 89, currency: 'usd' } }

Listing tasks

// List all tasks in a session
const all = await session.tasks.list()

// Filter by status
const running = await session.tasks.list({ status: class="cb-str">'running' })
const failed  = await session.tasks.list({ status: class="cb-str">'failed' })

Cancelling a task

Cancel a queued or running task. If the agent is already running, it will be terminated and the sandbox destroyed. Compute costs up to the cancellation point are still billed.

await session.tasks.cancel(class="cb-str">'task_abc123')

const task = await session.tasks.get(class="cb-str">'task_abc123')
console.log(task.status) class="cb-cmt">// 'cancelled'

Priority levels

Tasks support three priority levels that affect queue ordering:

highProcessed before normal and low priority tasks. Use for time-sensitive user-facing work.

normalDefault priority. Tasks are processed in submission order within the same priority.

lowBackground work. Processed after all higher-priority tasks. Use for batch jobs.

API reference

session.tasks.submit(opts)Promise<Task>Submit a new task. Returns immediately with a task ID and 'queued' status.

session.tasks.get(id)Promise<Task>Get the current status, progress, output, and cost of a task.

session.tasks.list(filters?)Promise<Task[]>List tasks in the session. Filter by status.

session.tasks.wait(id, opts?)Promise<Task>Long-poll until the task completes or timeout. Server holds the connection.

session.tasks.cancel(id)Promise<void>Cancel a queued or running task. Agent is terminated if running.

REST endpoints

POST/v1/sessions/:sid/tasksSubmit a task

GET/v1/sessions/:sid/tasksList tasks (filter: ?status=)

GET/v1/sessions/:sid/tasks/:idGet task status and result

GET/v1/sessions/:sid/tasks/:id/waitLong-poll for completion (?timeout=)

POST/v1/sessions/:sid/tasks/:id/cancelCancel a task