Skip to main content
POST

Overview

Cancels some of a goal’s cases while the goal keeps running. Name the cases by keys, states, key_prefix or a combination; a case must match every one you give. A request never cancels every case by default. Each cancelled case ends at once, with its sub-agents. Unspent funds return to the goal’s budget (or to the agent that funded it), its open questions to people are withdrawn, and its record’s state becomes cancelled. A case that had already ended, for example one left needs_a_person, only has its record closed. The agent is told which cases were cancelled. A cancelled case is not reopened by a later event for its key. A cases done check leaves cancelled cases out: they count neither as finished nor as unfinished, and not toward min_cases. One request cancels at most limit cases. While more match, the answer carries next_cursor: send the same request with it as cursor to go on.

Authentication

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

Path Parameters

string
required
The goal whose cases to cancel

Request Body

string[]
Case keys, 1 to 500
string[]
Record states such as open, waiting_on_carrier or needs_a_person
string
The start of the case keys, such as invoice-2026-10-
number
default:"100"
Most cases to cancel in this request, 1 to 500
string
next_cursor from the previous answer

Response

object[]
Each case cancelled: key, was (its state before) and refunded_usdc (what it had not spent)
string
The total returned to the goal by this request
number
Cases picked that could not be cancelled this time; the same request again retries them
string | null
Pass as cursor to cancel the next cases that match; null when none are left

Errors