/v1 routes require authentication and tenant scoping. Health, Run collection and Session list/activity permit application tokens; overview, pending and Fleet require an owner.
Health
GET /v1/health queries the database and returns process_id, boolean active_runs, api/database readiness, credentials, credential_access and execution. Optional health services can report not_configured. If credentials.state is unavailable, the route returns 503; otherwise its normal response is 200. Database errors use the server error handler. Inspect the fields, not just the HTTP status: the handler does not turn every degraded execution/access condition into 503.
GET /health/live is a separate unauthenticated liveness route returning {status:"alive"}. It does not query dependencies. Use readiness and lifecycle diagnostics for operational decisions rather than treating liveness as full health.
Session collection
GET /v1/sessions returns 200, {sessions:[...],offset,next_offset}. Limit defaults 25 (integer 1–100), offset defaults 0 (nonnegative integer), search defaults empty (≤200 characters), state defaults empty (≤40). Nonempty state is an exact Session-state filter. Search matches case-insensitive substrings of Session ID, Agent ID and definition name. Sort is created_at DESC, id DESC. Next offset is null at the observed end; concurrent inserts can shift pages.
Task activity
GET /v1/sessions/activity accepts period 24h (default) or 7d. It returns 200 with active_sessions, idle_sessions, paused_sessions, period, buckets and checked_at.
The categories are not necessarily disjoint: a paused Session with newly submitted work can be active and paused. Each bucket has start and active_sessions. The 24h period has hourly rolling buckets; 7d has daily rolling buckets anchored to query time, not calendar midnight. Terminal Run overlap ends at updated_at; nonterminal overlap extends to current time. These counts cover the tenant’s full data rather than the current Session list page. They measure task activity, not CPU utilization, HTTP traffic or billed compute.
Overview
GET /v1/overview returns 200, counters plus checked_at:
- ready_connections: undeleted, enabled, ready connection rows.
- open_sessions: state open, not all nonclosed Sessions.
- active_runs: all nonterminal Runs.
- pending_approvals: pending approval rows.
- pending_authorizations: Tool calls waiting_authorization.
- unknown_operations: all unknown resource operations, including acknowledged ones.
- active_agents: unarchived Agent templates.
Pending work
GET /v1/pending returns 200, {items:[...],offset,next_offset}. It uses the same limit/offset bounds as collection queries. Although shared parsing accepts search/state, the current SQL does not apply those two filters. Do not present them as supported filtering behavior on this endpoint.
Fleet snapshot
GET /v1/fleet returns 200, {sessions:[...]}, at most the latest 200 Sessions by creation time. There is no pagination contract. Each entry contains id, agent_id, definition, env_names, state, sandbox, created_at, updated_at, runtime_state, latest_run and resource_operations.
400 invalid_request. Owner-only route access with an application token returns 403 owner_token_required; missing identity returns 401. Use resource operations and Runs for object-specific investigation. Sources: query implementation, Fleet projection, HTTP routes. The monitoring contract review passed 36 checks through current handlers and real PostgreSQL in a newly migrated isolated schema. It covered roles, tenant isolation, pagination, search/state semantics, pending categories, activity overlap, Fleet bounds and readiness responses. The schema was removed afterward. These are controlled recorded-state fixtures, not a cloud monitoring or network transport acceptance run.
SDK examples: read separate operational views
Use an initialized owner client because overview and pending are owner-only. These helpers are read-only and retain each collection envelope, including its ownnext_offset. Defining the functions does not issue requests. The TypeScript snippets use the Hexagon import from SDK setup.
read_operations_page / readOperationsPage returns four separately queried observations, not one consistent snapshot. Pass the Session page’s next_offset back as session_offset / sessionOffset, and the pending page’s cursor independently as pending_offset / pendingOffset. A null cursor means that collection reached its observed end; do not reuse a Session offset for pending work or infer total tenant counts from either page. Concurrent changes can shift offset pages.
This example selects open Sessions only; it does not include every nonclosed Session. The overview’s unknown-operation count can include acknowledged operations that the pending queue omits, and activity categories can overlap. Do not add those counts together as a single fleet size. Pending rows are prompts for investigation: fetch the underlying approval, Tool call or resource operation and recheck current state before taking action. Do not turn this read helper into an automatic approval loop.
Generic request receives /health, because the SDK supplies /v1; passing /v1/health would duplicate that prefix. It returns JSON on success, while health 503 becomes an SDK exception and is not returned by this helper as a normal status object. A 200 can still contain degraded execution/access fields. These read calls do not prove live Provider state or global cleanup. Ordinary authentication, role, validation, network and decode failures propagate; the combined helper stops at the first failed read and has no partial-result recovery built in.
Compare views without inventing a total
Consider this recorded-state example: A is open with a running Run, B is paused with a queued Run, C is open without an active Run, and D is closed with a completed Run from the last hour. There are also two unknown resource operations, one acknowledged and one awaiting review.
Do not add active, idle and paused to estimate total Sessions, or compare a historical bucket directly with a current active count. Acknowledgement changes the investigation queue, not the recorded uncertainty or remote resource state. Fetch the underlying record before deciding what to do.
Interpret empty and unhealthy responses
stateis bounded text, not an enum in collection query parsing. An unrecognized state can return200with an empty list; it is not proof that no tasks exist. In contrast, an invalid activityperiodsuch as30dreturns400 invalid_request.- Search is a case-insensitive literal substring.
%and_are not SQL wildcard operators here. Use URL encoding so the server receives the intended search text. - A collection
next_offset: nulldescribes the observed end of that query. Fleet has no next cursor and silently caps its result at 200 Sessions; neither observation establishes global resource cleanup. - A closed Session’s Fleet
runtime_stateis forced tostopped, while the Session collection exposes the recorded Runtime binding state. Read each projection’s definition before treating differing fields as a new live observation. - Credential-unavailable Health returns
503with the health object, includingcredentials.state, rather than the usual{error:{code}}envelope.curl --fail-with-bodyretains that body while returning failure. The current SDK generic request maps this response to status 503 with codehttp_error; it does not return the health fields through the helper above. A separate liveness200does not override readiness failure.