---
title: "List stacks for an AI observer"
method: GET
path: "/api/stacks/platform/observation"
tags: ["Observation"]
---

# List stacks for an AI observer

`GET /api/stacks/platform/observation`

## Request

- Base URL: `https://localhost:1852`
- URL: `https://localhost:1852/api/stacks/platform/observation`
- Auth: HTTP bearer

Returns one page of the stacks on a node, projected for an Observe Only
token: name, status, running and total container counts, source, and whether
the stack is this instance. Stacks are ordered by name; the cursor is the
name of the last stack on the previous page, so a stack deleted between two
pages does not shift the rest of the list. A directory whose name has
characters outside letters, digits, `_`, and `-` is not listed, because
no per-stack route accepts it. `degraded` reports that the
underlying status evidence was incomplete. This is one of the five paths an
Observe Only token may reach. Requires `stack:read` permission.

## Query parameters

- `cursor` string
- `limit` integer

## Headers

- `x-node-id` integer

## Response `200`

One page of stacks wrapped in the observation envelope.

- object
  - `schemaVersion` 1, required
  - `generatedAt` integer, required: Epoch ms of the evidence behind the answer.
  - `data` ObservationStackListData, required
    - `degraded` boolean, required: True when the underlying status evidence was incomplete.
    - `total` integer, required: Total listed stacks on the node, across every page. A directory whose name has characters outside letters, digits, `_`, and `-` is not listed and is not counted.
    - `nextCursor` string, nullable, required: Name of the last stack on this page when more stacks exist, otherwise null.
    - `stacks` ObservationStackSummary[], required
      - `name` string, required
      - `status` 'running' | 'exited' | 'partial' | 'unknown', required
      - `running` integer, nullable, required: Running container count, or null when the node could not report it.
      - `total` integer, nullable, required: Total container count, or null when the node could not report it.
      - `source` 'local' | 'git', required
      - `isSelf` boolean, required: True when the stack is the instance serving the request.

## Other responses

- `400`: Invalid cursor or limit (`INVALID_CURSOR` or `INVALID_LIMIT`), 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.
- `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/platform/observation/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)