List tasks

GET

/tasks

const url = 'http://127.0.0.1:7700/api/tasks';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://127.0.0.1:7700/api/tasks \
  --header 'Authorization: Bearer <token>'

Every task the box knows, in the order they were created. The list is rebuilt from the action log at boot, so it includes finished and undone tasks.

Authorizations

deviceToken
accessToken

Responses

200

All tasks.

application/json

Array

object

title

required

A short name for people.

string

<= 200 characters

prompt

required

What the worker should do. For the fake worker, one command per line.

string

<= 100000 characters

workspace

required

A folder in BOX_HOME/workspaces. The task works on its own copy of it.

string

default: home /^[\w.-]+$/

worker

required

droid is Droid with Claude. fake runs scripted steps with no model, for tests.

string

default: droid

Allowed values: droid fake

tools

required

Tool names the task may call through its broker, such as wallet.pay.

Array<string>

default:

hosts

required

Hosts the task’s network may reach: example.com (any port), example.com:8080 (one port) or *.example.com (subdomains). Never localhost, a loopback or link-local address, or a whole top-level domain.

Array<string>

default: <= 50 items

model

Droid worker: the Claude model. haiku (cheap checks), sonnet (most work, the default), opus (hard tasks), or a full model id that starts with claude-. The task records the id it ran on.

string

budgetCents

required

Spending above this, in US cents, pauses the task for an OK. Default Settings defaultBudgetCents, 100 unless changed.

integer

<= 100000

source

required

Who started it, for the log and the portal: api, schedule, asi1, jira:BOX-12. From a paired device it is always phone:<device name>.

string

default: api

seat

The agent seat doing the work, such as Credit analyst. Shown in the audit.

string

<= 60 characters

droid

How Droid works on it. Ignored by the fake worker.

object

plan

Droid writes a plan first

boolean

autonomy

low gets no network beyond the model and asks before any spending. medium keeps its hosts and a budget of at most $1. high keeps what the task asked for. The box enforces this too.

string

Allowed values: low medium high

folder

Personal: the first real folder the task works on a copy of.

string

folders

Personal: every real folder the task works on.

Array<string>

required

string

state

required

queued created, not started. running the worker is working. waiting paused until an approval is answered. done finished; its changes are part of the workspace. failed stopped with an error; its changes are not applied. undone removed; its changes are gone and other tasks keep theirs.

string

Allowed values: queued running waiting done failed undone

user

required

The Linux user the task runs as, box-<id>.

string

layers

required

Finished tasks whose changes this task saw when it started, newest first.

Array<string>

costCents

required

Tool spending plus model cost, in US cents. Not rounded.

number

step

The latest step

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

error

Why it failed, as a sentence a person can read, such as Your Anthropic key was not accepted. Change it in Settings, Accounts & Keys.

string

summary

string

requestedBy

Business: the id of the person who asked for the task. Set by the box, never by the caller.

string

app

The app whose box started the task, whatever source it gave. Set by the box, never by the caller.

string

review

Personal, for a task on real folders: done and waiting for the owner, kept, stopped by a conflict, or undone.

string

Allowed values: pending kept conflict undone

Example

[
  {
    "id": "t3k9x2a1b2",
    "title": "Fix the failing test",
    "prompt": "Fix the failing test in this project.",
    "workspace": "project",
    "worker": "droid",
    "tools": [],
    "hosts": [],
    "budgetCents": 25,
    "source": "api",
    "state": "done",
    "user": "box-t3k9x2a1b2",
    "layers": [],
    "costCents": 5.2,
    "step": "All 4 tests pass.",
    "createdAt": "2026-10-24T09:12:03.411Z",
    "updatedAt": "2026-10-24T09:13:40.902Z"
  }
]