---
title: "Stack container status for an AI observer"
method: GET
path: "/api/stacks/{stackName}/observation/status"
tags: ["Observation"]
---

# Stack container status for an AI observer

`GET /api/stacks/{stackName}/observation/status`

## Request

- Base URL: `https://localhost:1852`
- URL: `https://localhost:1852/api/stacks/{stackName}/observation/status`
- Auth: HTTP bearer

Returns one stack's containers projected for an Observe Only token: name,
service, state, health, restart count, exit code, and start time. The
response carries at most 100 containers and sets `truncated` when the stack
has more. An `outcome` of `unavailable` is a successful response meaning the
node could not read its own containers at that moment; the container list is
empty and a later call may succeed. This is one of the five paths an Observe
Only token may reach. Requires `stack:read` permission for the named stack.

## Path parameters

- `stackName` string, required

## Headers

- `x-node-id` integer

## Response `200`

Container facts wrapped in the observation envelope.

- object
  - `schemaVersion` 1, required
  - `generatedAt` integer, required: Epoch ms of the evidence behind the answer.
  - `data` ObservationStackStatusData, required
    - `stack` string, required
    - `outcome` 'ok' | 'unavailable', required: `unavailable` means the node could not read its own containers at that moment. It is a successful response carrying no container list, not an error.
    - `containers` ObservationContainer[], required: At most 100 containers. Containers that are not running or are unhealthy come first, then those still starting, then the rest, each group ordered by name, so the cap drops healthy containers before it drops a problem one.
      - `name` string, required
      - `service` string, nullable, required
      - `state` 'created' | 'running' | 'paused' | 'restarting' | 'removing' | 'exited' | 'dead' | 'other', required
      - `health` 'healthy' | 'unhealthy' | 'starting' | 'none' | 'null', nullable, required
      - `restartCount` integer, required
      - `exitCode` integer, nullable, required
      - `startedAt` string, nullable, required: ISO 8601 start time, or null when Docker does not report one.
    - `truncated` boolean, required: True when the stack has more containers than the response carries.

## Other responses

- `400`: Invalid stack name, or `capability_unavailable` when a targeted remote does not advertise `agent-observation-v1`.
- `401`: Authentication required. Provide a valid Bearer token. On a remote node, a 401 that carries an `x-sencho-proxy: 1` response header came from the node rejecting the API token stored for it on the hub, not from the caller's own token.
- `403`: Insufficient permissions or license tier.
- `404`: The stack does not exist on the node (`STACK_NOT_FOUND`).
- `500`: Internal server error.
- `503`: The targeted remote node is down or did not give a usable answer to the capability check (`node_unreachable`). A disconnected Pilot tunnel or a node with no API URL or token configured also answers 503, without a code. A Distributed API Proxy node that answers the check but rejects the API token stored for it answers 401 without a code, not 503.

## Changes

- **2026-11-01** `bef9c9739469`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/studio-saelix/apis/sencho-api/changes/api/stacks/:stackName/observation/status/get.md)

---

[API](https://skmtc.dev/studio-saelix/apis/sencho-api.md) - [All operations](https://skmtc.dev/studio-saelix/apis/sencho-api/llms.txt) - [OpenAPI document](https://skmtc.dev/studio-saelix/apis/sencho-api/revisions/1f7572eb735f?raw)