REST API

Result and statuses

GET /api/tasks/{uuid} returns the current status and, for finished tasks, the result in the turn field.

GET /api/tasks/{uuid}

Lost a uuid or need an overview of all your tasks? There's a task list with a status filter.

Response

Field	Type	Description
`uuid`	string	Task identifier.
`status`	string	Current status (see below).
`turn`	object \| null	The result from Aist Core. Set on `completed`. See Turn structure.
`error`	string \| null	A human-readable reason on `failed`; on `canceled` — the `reason` you passed.
`created_at`	string	When the task was created.
`completed_at`	string \| null	When the task reached a terminal status.
`pending_tool_calls`	array	Only on `interrupted` — client tool calls waiting for an answer.

Status lifecycle

pending ──▶ processing ──┬──▶ completed        # success, turn is set
                         ├──▶ failed            # error, error is set
                         └──▶ interrupted ──┬──▶ processing ──▶ …   # waiting for client_tools
                                            └──▶ canceled          # you declined to answer

Status	Meaning
`pending`	The task is queued and hasn't been sent to Aist Core yet.
`processing`	Aist Core has accepted the turn and is working on it.
`interrupted`	The model called a client tool and is waiting for your result. See Client tools.
`completed`	Terminal. The result is in `turn`.
`failed`	Terminal. The reason is in `error`.
`canceled`	Terminal. You gave up on an interrupted task via `POST /api/tasks/{uuid}/cancel` — the reason is in `error`.

The terminal statuses are completed, failed and canceled: once there, the task doesn't change. interrupted is intermediate: it needs action from you and goes back to processing after you send the tool results, or ends as canceled if you decline to answer.

Polling strategy

Poll GET /api/tasks/{uuid} every ~1–2 s until status becomes terminal (or interrupted, if you use client tools). The SDK does this for you — see waitForTask.

Owner-only access

A task can only be fetched by the same user (sub in the JWT) who created it — otherwise you get 403. Completed, failed and canceled tasks are kept for 30 days and then deleted.