Skip to content
GurtOS

Get a task with its approvals and log

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

The task, every approval it asked for, and every action log event that belongs to it, in order.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The task id.

Example 

t3k9x2a1b2

Responses

Section titled “Responses”

200

Section titled “200”

The task, its approvals and its events.

Media typeapplication/json
object
task
required
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>
id
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
approvals
required
Array<object>
object
id
required

<task id>.budget.<action> for the box’s own spend question, <task id>.task.<key> for a question the task asked, <task id>.tool.<call>.ask.<hash> for one a tool asked, <task id>.shadow.<action> for a Business shadow request. The same key asked twice is the same approval. A task can only name keys under task., so it cannot pre-answer the box’s own questions.

string
task
required
string
question
required

The question shown to people.

string
costCents
required

The spending being asked about

number
payee

Who gets paid

string
purpose

What the spend or action is for.

string
state
required
string
Allowed values: pending approved denied
by

Who answered: a paired device’s name, what the box’s own screen sent (such as box screen), jira:<name>, asi1, undo, or task ended. On Business, the person’s name.

string
person

Business: the id of the person who answered.

string
via

Business: the phone or screen the answer came from. A native app’s auth is kept here as reported.

string
askedBy

Business: the id of the person who asked for the task. They may not answer it.

string
route

Business: where the policy sent a request, and why.

object
rule
required

The policy line that matched, such as Over $10,000 goes to the Controller.

string
to
required

Who it goes to as the policy says it: the Controller, IT, any approver.

string
amountCents
required

The amount the rules and limits were checked against

integer
people
required

The people who could approve it when it was asked.

Array<object>
object
id
string
name
string
why
required

One sentence for people.

string
shadow

Business shadow mode: the seat this is a suggestion from.

string
events
required
Array
One of: discriminator: type

One line of the action log. See Log events.

object
seq
required

The line number in log.jsonl

integer
>= 1
at
required
string format: date-time
prev

The SHA-256 of the previous line

string
task
required

The task the event belongs to

string
who

Business only: who is behind the event.

object
asked
string
trigger
string
seat
string
approver
string
by
string
type
required
Allowed value: task.created
spec
required

The spec with every default filled in.

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

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

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

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

string
default: droid
Allowed values: droid fake
tools

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

Array<string>
default:
hosts

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

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

integer
<= 100000
source

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>
user
required
string
requestedBy
string
app
string

Example 

{
  "task": {
    "workspace": "home",
    "worker": "droid",
    "tools": [],
    "hosts": [],
    "source": "api",
    "droid": {
      "autonomy": "low"
    },
    "id": "t3k9x2a1b2",
    "state": "queued",
    "user": "box-t3k9x2a1b2",
    "review": "pending"
  },
  "approvals": [
    {
      "state": "pending"
    }
  ],
  "events": [
    {
      "type": "task.created",
      "spec": {
        "workspace": "home",
        "worker": "droid",
        "tools": [],
        "hosts": [],
        "source": "api",
        "droid": {
          "autonomy": "low"
        }
      }
    }
  ]
}

400

Section titled “400”

No task with this id.

Media typeapplication/json
object
error
required

What went wrong

string

Example 

{
  "error": "no task t3k9x2a1b2"
}