---
title: "Observe retained lifecycle evidence and resource liability"
method: GET
path: "/v1/agents/{id}/observations"
tags: ["Managed agents"]
---

# Observe retained lifecycle evidence and resource liability

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

## Request

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

Requires authentication and an agent definition owned by the authenticated tenant. Returns 404 when the definition does not exist or belongs to another tenant. Returns one read-only database snapshot with a paginated run projection. Counts cover all runs of the definition. Missing timestamps and productive activity remain explicitly unmeasured. Available for retained work when new admission is disabled.

## Path parameters

- `id` string, required

## Query parameters

- `after` string
- `limit` integer

## Response `200`

Success

- ManagedAgentObservations
  - `schema_version` 'managed-agent-observations-v1', required: Version of these lifecycle observation semantics.
  - `agent_id` string, required
  - `observed_at` string, date-time, required: Database observation time for this response. Subsequent pages can observe newer state.
  - `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.
  - `productive_active_agents` unknown, required
  - `productive_active_agents_status` 'measurement_unavailable', required: Whether productive agent concurrency is independently measured.
  - `runs` ManagedAgentRunObservation[], required
    - `run_id` string, required
    - `revision` integer, required
    - `status` 'queued' | 'starting' | 'running' | 'waiting' | 'recovering' | 'blocked' | 'completed' | 'cancelled', required
    - `attempt_count` integer, required
    - `submitted_at` string, date-time, required
    - `first_allocation_created_at` string, date-time, nullable, required: Earliest retained attempt creation time. A warm allocation can predate submission.
    - `first_boot_observed_at` string, date-time, nullable, required: Earliest retained sandbox boot binding. A warm boot can predate submission.
    - `first_driver_started_at` string, date-time, nullable, required: First recorded driver process start. This is not proof of useful task work.
    - `first_session_started_at` string, date-time, nullable, required: First durable driver session receipt.
    - `first_step_completed_at` string, date-time, nullable, required: First retained completed step receipt. A completed step does not establish accepted task output.
    - `first_useful_command_at` unknown, required
    - `first_useful_command_status` 'measurement_unavailable', required: Whether useful command activity is independently measured.
    - `result_committed_at` string, date-time, nullable, required: Logical result commit time for completed runs. Customer acceptance is checked separately.
    - `cleanup_completed_at` string, date-time, nullable, required: Latest attempt closure when every associated attempt and retained resource liability is settled. Otherwise null.
    - `open_attempts` integer, required: Attempts not recorded closed, including admitted, starting, running and draining allocations.
    - `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.
  - `next_after` string, required: Cursor for the next page in ascending run ID order, or an empty string. Each page has its own database snapshot.

## Other responses

- `404`: The agent definition does not exist or is not owned by the authenticated 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** `d9c4c840fb2d`: 2 breaking, 1 info
  - the `productive_active_agents` response's property type changed from `integer, null` to `null` for status `200`
  - the `runs/items/first_useful_command_at` response's property type changed from `string, null` to `null`, and format from `date-time` to no format for status `200`
  - added the non-success response with the status `404`
- **2026-09-27** `90c4cb8514af`: 1 info
  - endpoint added

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