Skip to main content
POST

Overview

Cancels a compute goal and credits its unspent budget back to your agent as OneShot credits. If anything was spent, one receipt is written for the spent amount. If tool calls are still in flight, their reservations can’t be refunded yet. The goal is still cancelled, but the call returns 202 with status: "pending_settlement" and the refund is credited once those reservations settle.

Authentication

A signed write proof or an access token: see Authentication schemes. Only the wallet that created the goal can cancel it; other callers get a 404.

Path Parameters

string
required
Goal ID to cancel

Request Body

string
Reason for cancelling (recorded on the goal’s event log)

Response

string
The cancelled goal ID
string
cancelled, or the current status (completed or cancelled) if already finished
string
Cancellation result, or why cancellation changed nothing
string
Amount spent (USDC); omitted if already finished
string
Amount credited back as OneShot credits (USDC); omitted if already finished
Cancelling a goal that is already completed or cancelled changes nothing and returns 200 with its current status.

Tool holds

A goal that requests a tool it cannot proceed without (request_tool with blocking: true, where the tool needs a key, licence, customer account or action channel) waits in awaiting_tool. Its sessions keep their saved steps and spend. The owner is notified in-app. If the goal has a webhook URL, an unregulated signed goal.awaiting_tool webhook also names the requested tool. Regulated webhooks carry only IDs, status, timestamps and an authenticated content-read path. A hold ends when:
  • The tool ships or the owner continues without it: the goal resumes.
  • The owner cancels it here.
  • 7 days pass: the goal is cancelled with end_reason: tool_timeout and its unused budget becomes credit.
A blocking request for an open source never holds: the goal is told to get the answer with its own code in its computer.