Skip to main content
These routes back the savings figures on the TokenOps screen, the per-turn and tool-call views of a session, and the Overview map with its list of problems. The other TokenOps and observability routes (finops/dashboard, finops/insights, session/list, trace/{id} and more) are in the generated spec — see API reference.

Authentication

Send the session JWT from POST /api/auth/login as Authorization: Bearer <token>, or use the dashboard cookie. Every route on this page is open to any authenticated user. What each caller sees is narrowed inside the route, as described per endpoint. A superuser sees everything. Requests without a valid session get 401 with { "data": null, "status_code": 401, "message": "..." }. Unless noted, other errors on these routes are plain text, not JSON.

Endpoints


Get savings

GET /api/observability/finops/savings Reports how many tokens and dollars the cost-reduction features saved in a time window, compared with what the same traffic would have cost without them. Use it to show the return on reducing cost, or to find agents that would benefit from turning optimizations on. The TokenOps screen and agent pages read it. Auth: session JWT or dashboard cookie. Role: any authenticated user.

Query parameters

The window and filters match GET /api/observability/finops/dashboard, so you can reuse the same filter state.

Example

Response fields

Savings figures. total, each by_program entry, each layer, each by_agent row and each by_session row carry the same figures: Other fields:

What you see

  • A non-superuser sees only agents they can access.
Plans: Pro and Enterprise. Self-hosted: Enterprise license.
When an org-unit filter applies to your account, figures cover your own calls only. Filtering by an agent you own lifts that limit, so an owner sees all usage of their agent.

Errors


Get per-turn cost for a session

GET /api/observability/session/{session_id}/turns Returns one row per turn of a chat session, with the model calls, tokens and cost that turn incurred. A turn is one user message and everything the agents did to answer it. Use it to find which turn of a conversation drove the spend. Figures come from the billing ledger, so they don’t depend on trace retention. CLI: nasiko observe turns. Auth: session JWT or dashboard cookie. Role: any authenticated user. You see turns only in your own sessions; a superuser sees any session.

Path parameters

Example

Turns are ordered oldest first.

Errors

Notes

  • An unknown session, a session that isn’t yours, and a session with no billed model calls all return 200 with "turns": [].

List tool calls in a session

GET /api/observability/session/{session_id}/tool-calls Returns every tool call recorded for a chat session, oldest first, with arguments, output, status and duration. Stored tool calls outlive trace retention, so this works for older sessions whose traces have expired. The session view in the dashboard reads it. Auth: session JWT or dashboard cookie. Role: any authenticated user. You can read only your own sessions; a superuser can read any session.

Path parameters

Example

Errors

Notes

  • Only calls whose turn the server itself recorded for this session are returned. A span that claims the session but belongs to a different conversation is left out.

Get the estate

GET /api/overview/estate Returns everything the Overview map draws: the people, agents, coding harnesses, workflows, MCP tools, routers, providers and models you can see, the connections between them, daily spend, and the problems, cause chains and savings opportunities found in that data. Use it to build your own fleet view or to pull the current problem list. Auth: session JWT or dashboard cookie. Role: any authenticated user. The estate covers the agents you can list and the people visible to you; a superuser sees the whole estate.

Query parameters

Example

Abbreviated response — each array holds one object per node:

Top-level fields

Node IDs are UUIDs, except models (model:<name>), providers (provider:<name>), and the direct path coding harnesses take with no router (router:direct).

Problem fields

Errors

Notes

  • Problems compare each thing with its own recent past (this week against last week, or its own 30-day baseline), not with a fleet-wide bar. A rule needs enough runs to fire, so a handful of failures never raises a problem.

Update a problem

PATCH /api/overview/problems/{id} Records a decision about a problem: who owns it, a snooze, or that it’s handled. The dashboard’s Assign, I’ll take it, Snooze and Mark handled controls call this. Returns the updated problem. Auth: session JWT or dashboard cookie. Role: any authenticated user who can see the problem in their estate.

Path parameters

Request body

Send exactly one of these fields. Unknown fields are rejected.

Example

The response carries the full problem object; fields are trimmed here for space. See Problem fields.

Errors

Notes

  • The problem must exist in your estate over the last 30 days. A problem that appears only in a 7d or 90d view and not in the 30-day view returns 404.
  • Decisions are shared: everyone who sees the problem sees the same owner, snooze and handled state.
  • A snooze ends on its own at snoozed_until. Handled lasts until the end of the UTC day it was set. If the rule still fires the next day, the problem shows again.
  • Setting the same value twice is safe.