---
title: "Fence new group work and continue member cleanup"
method: POST
path: "/v1/agent-groups/{id}/cancel"
tags: ["Managed agents"]
---

# Fence new group work and continue member cleanup

`POST /v1/agent-groups/{id}/cancel`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/agent-groups/{id}/cancel`
- Auth: HTTP bearer

Requires authentication and a group owned by the authenticated tenant. A missing or foreign-owned group returns 404. Commits a durable cancellation fence. Existing executors asynchronously cancel nonterminal members and reconcile their allocations, including when new admission is disabled. The 202 response does not claim completed physical cleanup. Previously completed results are retained.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string, required

## Response `202`

Accepted

- ManagedAgentGroup
  - `attempt_budget_usd` number, nullable: Immutable fixed attempt reservation accepted for this group and its child runs. Absent for the legacy allocation policy.
  - `id` string, required
  - `name` string, required
  - `agent_id` string, required
  - `revision` integer, required
  - `status` 'active' | 'cancelled', required: Admission lifecycle. Use logical_runs for task progress and allocations for remaining cleanup.
  - `budget_usd` number, required: Zero means account funding without a group spending limit. A positive value is the group's accepted compute sublimit of any positive deployment budget. Payment, available credits, deployment limits and accepted attempt limits still apply.
  - `max_active` integer, required: Authorized attempts in admitting, starting or running state, including retained waiting workers. This is not measured productive concurrency.
  - `max_held` integer, required: Allocations awaiting confirmed physical cleanup, including provisioning, draining and uncertain resources. Pending accounting retains spending reservations after physical capacity is released. Must be at least max_active and at most the deployment worker limit.
  - `max_pending` integer, required
  - `max_retained_runs` integer, required: Persisted admission cap for runs whose payloads have not expired. Completion alone does not release this count.
  - `created_at` string, date-time, required
  - `cancelled_at` string, date-time, nullable, required
  - `logical_runs` ManagedAgentLogicalRunCounts, required
    - `total` integer, required
    - `queued` integer, required
    - `starting` integer, required
    - `running` integer, required
    - `waiting` integer, required
    - `recovering` integer, required
    - `blocked` integer, required
    - `completed` integer, required
    - `cancelled` integer, required
  - `allocations` ManagedAgentAllocationObservations, required
    - `total_attempts` integer, required
    - `open_attempts` integer, required: Attempts not recorded closed, including admitted, starting, running and draining allocations.
    - `starting_attempts` integer, required
    - `draining_attempts` integer, required
    - `warm_attempts` integer, required: Open attempts not assigned to a logical run.
    - `unresolved_attempts` integer, required: Attempts with uncertain creation or retained candidate cleanup and accounting incidents.
    - `cleanup_pending_attempts` integer, required: Attempts still open or lacking settled cleanup, including retained resource, lease, allowance or storage liability. Includes active attempts and does not mean stop was requested.
    - `unreleased_instances` integer, required: Known instance records without removal evidence. This is not a healthy instance count.
  - `retained_runs` integer, required
  - `cost_usd` number, required: Settled attempt costs and recorded compute charges for unsettled attempts without a spending cap, within the deployment account.
  - `reserved_usd` number, required: Full accepted budget liability of unsettled assigned attempts with a spending cap, plus outstanding account funding reservations for attempts without a cap. A closed marker alone cannot release these reservations.
  - `active_authorized_attempts` integer, required: Attempts in admitting, starting or running state. Includes retained waiting or recovering workers and does not establish productive activity.
  - `work_status` 'empty' | 'pending' | 'running' | 'waiting' | 'blocked' | 'completed' | 'cancelled' | 'cancelling', required: Read-only summary of the current logical runs, independent of group admission and remaining cleanup.
  - `blocked_reasons` ManagedAgentGroupBlockedReason[], required: Sorted public categories counting each waiting or blocked logical run once. Active running work is excluded unless group cancellation fences it. Empty groups return an empty array.
    - `reason` 'admission_rejected' | 'admission_retry' | 'allocation_cleanup' | 'attention_required' | 'budget' | 'cancelling' | 'children' | 'dependencies' | 'dependency_blocked' | 'execution_capacity' | 'external_outcome_unknown' | 'messages' | 'queued' | 'recovering' | 'session' | 'signal' | 'starting' | 'timer' | 'waiting' | 'workspace_capacity', required
    - `runs` integer, required
  - `cleanup_status` 'complete' | 'pending' | 'unresolved', required: Separate from useful task completion. Unresolved resource, accounting or message publication evidence takes precedence, followed by pending allocation or inbox cleanup.
  - `broker_limits` ManagedBrokerLimits: Immutable lifetime request, token, read-byte and invocation-history ceilings. At least one operation kind must have a positive request allowance. Model requests require positive input and output allowances. Zero model or tool requests require their matching unit allowances to be zero. Limits must fit an independently configured account policy. Waiting and unknown outcomes retain their counted liabilities. These units do not represent model prices.
    - `model_requests` integer, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `tool_requests` integer, required
    - `read_bytes` integer, required
    - `max_concurrent` integer, required
    - `max_retained_invocations` integer, required
    - `max_retained_bytes` integer, required
  - `broker_usage` ManagedBrokerUsage
    - `model` ManagedBrokerModelUsage, required: Active counts dispatched requests. Unresolved counts dispatched effects whose results remain unknown. Both retain concurrency and reserved units until authoritative settlement.
      - `requests_used` integer, required
      - `requests_reserved` integer, required
      - `active` integer, required
      - `unresolved` integer, required
      - `input_tokens_used` integer, required
      - `output_tokens_used` integer, required
      - `input_tokens_reserved` integer, required
      - `output_tokens_reserved` integer, required
    - `tools` ManagedBrokerToolUsage, required
      - `requests_used` integer, required
      - `requests_reserved` integer, required
      - `active` integer, required
      - `unresolved` integer, required
      - `read_bytes_used` integer, required
      - `read_bytes_reserved` integer, required
    - `waits` ManagedBrokerWait[], required
      - `reason` 'model_request_limit' | 'model_token_limit' | 'tool_request_limit' | 'tool_byte_limit' | 'broker_concurrency_limit' | 'broker_outcome_unknown' | 'broker_unavailable', required
      - `requests` integer, required
  - `peer_messaging` boolean: Read-only availability of direct task messaging, assigned automatically when this group is admitted on a supported deployment. Existing groups retain their original availability.
  - `peer_usage` ManagedPeerUsage: Lifetime accepted message counts and payload bytes. Received means committed to the recipient journal. It does not prove the application acted on a message. Uncertain publication ownership remains visible until independently reconciled.
    - `messages` integer, required
    - `bytes` integer, required
    - `pending` integer, required
    - `received` integer, required
    - `undelivered` integer, required
    - `cleanup_pending` integer, required
    - `cleanup_unresolved` integer, required
    - `max_messages` integer, required
    - `max_bytes` integer, required

## Other responses

- `404`: Group or definition is missing or belongs to another tenant
- `default`: Operation refused with a diagnostic and next action

## Changes

- **2026-10-01** `ba84c74aeec8`: 1 info
  - endpoint added
- **2026-10-01** `544fef290a54`: 1 breaking
  - api path removed without deprecation
- **2026-09-27** `7e2854e29425`: 1 warning, 2 info
  - added the new `messages` enum value to the `blocked_reasons/items/reason` response property for the response status `202`
  - added the optional property `peer_messaging` to the response with the `202` status
  - added the optional property `peer_usage` to the response with the `202` status
- **2026-09-27** `6beb2f6dc3ca`: 1 info
  - added the optional property `attempt_budget_usd` to the response with the `202` status
- **2026-09-27** `45888581ade0`: 2 info
  - added the optional property `broker_limits` to the response with the `202` status
  - added the optional property `broker_usage` to the response with the `202` status

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/agent-groups/:id/cancel/post.md)

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)