---
title: "Discover retained groups for an agent definition"
method: GET
path: "/v1/agents/{id}/groups"
tags: ["Managed agents"]
---

# Discover retained groups for an agent definition

`GET /v1/agents/{id}/groups`

## Request

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

Accepts API-key and console-session authentication. Returns retained active and cancelled groups for the owned definition, including while new admission is disabled. Groups are ordered by creation time descending, then group ID descending. Each page is a consistent read-only snapshot. Newer groups are discovered by restarting from the first page. Listing does not grant admission entitlement, increase execution limits or reserve spending.

## Path parameters

- `id` string, required

## Query parameters

- `after` string
- `limit` integer

## Response `200`

Retained groups in descending creation order

- object
  - `groups` ManagedAgentGroup[], required
    - `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
  - `next_after` string, required: Use as after for the next page. Empty when no older groups remain.

## Other responses

- `404`: Definition or cursor is missing or not owned by this tenant and definition
- `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 `groups/items/blocked_reasons/items/reason` response property for the response status `200`
  - added the optional property `groups/items/peer_messaging` to the response with the `200` status
  - added the optional property `groups/items/peer_usage` to the response with the `200` status
- **2026-09-27** `dba96f92c4ac`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/agents/:id/groups/get.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)