Async tasks
Agent task lifecycle, the Task envelope, polling, callbacks, and cancellation.
Agent skills that take longer than an HTTP turn return 202 + a Task envelope.
The task is queued, runs asynchronously, and can be observed by polling or
callbacks:
Task envelope
The create response, GET /v1/tasks/{task_id}, and the callback POST body all return the same structure:
| Field | Description |
|---|---|
task_id | task_-prefixed task ID; stable across idempotent retries |
status | queued / running / succeeded / failed / canceled |
capability | Capability name, e.g. text_to_video |
model / resolved_model | Requested model (may be auto) / model that actually ran |
input | Normalized echo of the input |
output | Artifacts; present only on succeeded. Structure documented on each capability page |
progress | { percent, stage, message }; meaningful only while running |
warnings[] | Reserved; currently always an empty list |
error | { code, message, retryable }; present only on failed |
usage / billing | Billing details → Billing & usage |
callback | Callback delivery status → Callbacks |
metadata | Reserved; accepted at creation, currently always null in responses |
created_at / started_at / completed_at | Lifecycle timestamps (UTC) |
links | { self, cancel } |
Polling, listing, and cancellation
| Operation | Endpoint | Description |
|---|---|---|
| Get one | GET /v1/tasks/{task_id} | Returns the full envelope; poll at ~5s intervals until a terminal state |
| List | GET /v1/tasks?limit=100 | Cursor-paginated summaries; excludes output/usage |
| Cancel | POST /v1/tasks/{task_id}/cancel | Idempotent; terminal tasks are returned as-is, and an in-flight stop succeeds only when confirmed |
Before remote execution starts, cancellation stops the task and releases its
prepaid credits. Once execution has started, Beatra returns canceled only
when the stop is confirmed. A 409 means execution continues: do not claim the
task stopped or promise a refund, do not submit a replacement, and continue polling
the same task to its terminal state.
MiniMax H3 can confirm cancellation only while its upstream task is still
queued. Once it is running, Beatra returns 409 and does not refund the
task; the upstream DELETE operation is not used because it would not represent
a confirmed cancellation.
Explicit model vs auto
- An explicitly specified
modelis never silently replaced: if it does not support a requested parameter, the request fails immediately with422 unsupported_optionnaming the field. - With
model: "auto", choosing and switching the concrete model is the platform's job by design; the terminal task'sresolved_modelrecords which model actually ran.
Storing artifacts
Resource URLs in output are CDN addresses. Copy them to your own storage promptly after fetching results — do not treat them as permanent links.