Skip to main content
GET

Overview

Status, progress and requested tools.

Authentication

A signed read proof or an access token: see Authentication schemes. Only the creating wallet can read it; others get 404.

Path Parameters

string
required
Goal ID from the create endpoint

Response

string
Goal ID
string
active, paused, awaiting_connection, awaiting_budget, awaiting_tool, awaiting_setup, awaiting_confirmation, completed, failed, or cancelled. awaiting_confirmation has no done-check; confirm completion.
object
Progress: since, units_done, units_left and cost_to_finish, or price_per_unit for open goals.
object
since and requires, with account needs and actions.
object
since and requires, with missing systems and connect_url.
array
Requests: id, need summary, status, optional tool_name.
string
Goal name
string
Full objective text
string
Phase name the orchestrator last set, or null
any
Plan the orchestrator last set, or null. Free-form.
string
Platform-paid USDC; budget unaffected. Default zero.
object
total, spent, reserved, remaining (all USDC strings), or null if the goal has no budget record
string
Soul agent ID when the goal was created with soul_slug, else null
string
The goal’s deadline, or null. Once it passes, nothing new starts and the done-check decides (or, with no check, the goal waits for you).
object
The goal’s done-check, or null when its owner confirms
string
Final answer, or null. result_at records its timestamp; files and tool results are at outputs.
object
Latest evaluation: kind, passed, observed, required, detail, evaluated_at, attempt; null before evaluation.
string
Ending, or null:
  • check_passed, owner_confirmed, planner_failed.
  • check_failed: unmet after three attempts.
  • budget_exhausted.
  • deadline_passed: unmet at the deadline.
  • impossible: proof verified in code.
  • impossible_unverified: no verifiable proof; disputable.
  • connection_timeout, tool_timeout, setup_timeout: a hold expired.
  • runner_retired: budget credited; start a new goal.
After budget_hold_days (default 7), budget holds end failed/budget_exhausted and credit the remainder. Only this ending allows funding to reactivate.
string
When the goal was created
string
When the goal ended
string
Last orchestrator wake
string
Next scheduled wake, if any
string
Creation timestamp
object
Recurring goals only: cron, budget_per_run, max_runs, run_count, last_run_at, next_run_at

Connection holds

Missing payer connections hold goals without sessions or spend; requires names systems and connect URLs. Connecting them or starting anyway releases the goal. After 7 days, unused budget becomes credit (unstarted goals recover the whole charge). Runtime holds keep spend and saved steps. For awaiting_tool, see tool holds.

Setup holds

Unmet setup holds awaiting_setup until its account reader reports ready. Setup is a separate owner purchase. After 7 days: cancelled/setup_timeout, unused goal funds refunded; bought domains stay owned. Lost quoted-ready prerequisites instead refund the entire payment including quote fee. All holds preserve steps, replay release messages after queue failure, and recover deferred refunds after settlement.