> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Cases

> Cancel one case, or cases by state or key prefix, and return their unspent budget

## Overview

Cancels some of a goal's [cases](https://docs.oneshotagent.com/api-reference/compute/cases.md) 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](https://docs.oneshotagent.com/api-reference/openapi.md#authentication-schemes).

Only the wallet that created the goal can cancel its cases; other callers get a `404`.

## Path Parameters

**goalId** `string` *required*

The goal whose cases to cancel

## Request Body

**keys** `string[]`

Case keys, 1 to 500

**states** `string[]`

Record states such as `open`, `waiting_on_carrier` or `needs_a_person`

**key\_prefix** `string`

The start of the case keys, such as `invoice-2026-10-`

**limit** `number` (default: 100)

Most cases to cancel in this request, 1 to 500

**cursor** `string`

`next_cursor` from the previous answer

## Response

**data.cancelled** `object[]`

Each case cancelled: `key`, `was` (its state before) and `refunded_usdc` (what it had not spent)

**data.refunded\_usdc** `string`

The total returned to the goal by this request

**data.skipped** `number`

Cases picked that could not be cancelled this time; the same request again retries them

**data.next\_cursor** `string | null`

Pass as `cursor` to cancel the next cases that match; `null` when none are left

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/compute/3f2b9c1e-8d4a-4f6b-9e2a-7c1d5b8a0f42/cases/cancel \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -H "x-agent-proof: <base64 EIP-712 proof, scope write>" \
  -d '{ "states": ["open"], "key_prefix": "invoice-2026-10-", "limit": 100 }'
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "goal_id": "3f2b9c1e-8d4a-4f6b-9e2a-7c1d5b8a0f42",
    "cancelled": [
      { "key": "invoice-2026-10-0007", "was": "open", "refunded_usdc": "<unspent>" }
    ],
    "refunded_usdc": "<total>",
    "skipped": 0,
    "next_cursor": null
  }
}
```

## Errors

| Code | Status | When |
| - | - | - |
| `invalid_request` | 400 | No `keys`, `states` or `key_prefix`, or one of them, `limit` or `cursor` is malformed |
| `goal_ended` | 409 | The goal has ended; its cases ended with it |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.