POST
Run Task

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
background
boolean
default:false

Queue the run and return at once (202) instead of waiting for its result.

files
Files · object

One PDF per declared file input, by name.

idempotency_key
string | null

Resending the same key returns the existing run instead of starting another.

Required string length: 1 - 255
metadata
Metadata · object

Up to 16 string labels of your own, for filtering.

task
TaskConfig · object | null

A complete task definition, run and stored nowhere else.

task_id
string<uuid> | null

A task in this workspace. Exclusive with task.

task_override
TaskPatch · object | null

Changes for this run only: objects deep-merge, lists replace, null clears.

task_version

Which version of task_id to run. Omit for the published one; "draft" runs the unpublished config, held to the publish checks.

vars
Vars · object

Values for the task's text inputs, by name. Undeclared names are refused.

Response

Successful Response

One run in full: the config it ran, its inputs, its trace and its usage.

attempts
integer
default:0
required
background
boolean
default:false
required
billing_status
string
default:pending
required
cancel_requested_at
string<date-time> | null
required
config
TaskConfig · object | null
required

LiveKit's AgentTask: an agent with a typed result, on someone else's stack.

It declares no channel, no media and no greeting. Entered by an agent it speaks with that call's voice and hears with its ears; run on its own from POST /task-runs it is an LLM with tools and nobody to talk to. Which of the two happens is the caller's, never the task's.

content_deleted_at
string<date-time> | null
required
content_expires_at
string<date-time> | null
required
created_at
string<date-time>
required
duration_ms
integer | null
required
ended_at
string<date-time> | null
required
error
TaskRunError · object | null
required
files
TaskRunFile · object[]
required
id
string<uuid>
required
idempotency_key
string | null
required
max_steps
integer
default:0
required
metadata
Metadata · object
required
output
Output · object | null
required
provider_cost
number | null
required
started_at
string<date-time> | null
required
status
enum<string>
required
Available options:
queued,
running,
completed,
failed,
canceled
steps_used
integer
default:0
required
task_id
string<uuid> | null
required
task_name
string | null
required
task_version
integer | null
required
trace
TraceStepResponse · object[]
required
tries
integer
default:0
required
usage
LLMUsage · object[]
required
vars
Vars · object
required