> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TokenOps and observability API

> Savings, per-turn session cost, stored tool calls, and the Overview estate with its problems.

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](https://docs.nasiko.com/api-reference/overview.md).

## Authentication

Send the session JWT from [`POST /api/auth/login`](https://docs.nasiko.com/api-reference/account) 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

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/observability/finops/savings` | Tokens and dollars saved by optimizations, overall and per program, agent and session |
| `GET` | `/api/observability/session/{session_id}/turns` | Tokens and cost per turn of a chat session |
| `GET` | `/api/observability/session/{session_id}/tool-calls` | Every stored tool call in a chat session |
| `GET` | `/api/overview/estate` | Everything the Overview map draws, plus problems, cause chains and opportunities |
| `PATCH` | `/api/overview/problems/{id}` | Assign, snooze, or mark a problem handled |

***

## 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](https://docs.nasiko.com/tokenops/reduce-cost.md), 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.

| Name | Type | Default | Description |
| - | - | - | - |
| `start_time` | ISO-8601 timestamp | 30 days ago | Window start |
| `end_time` | ISO-8601 timestamp | Now | Window end |
| `range` | string | — | `24h`, `7d`, or `30d`. When set, the window becomes this long, ending at `end_time` (or now), and `start_time` is ignored |
| `agent_id` | string | — | Agent UUID or agent name |
| `model` | string | — | Only calls to this model |
| `provider` | string | — | Only calls to this provider |
| `scope` | string | `total` | `total` returns both the agent and session breakdowns. `agent` returns only `by_agent`. `session` returns only `by_session` |
| `session_id` | string | — | One chat session's savings. Implies `scope=session` |
| `limit` | integer | `25` | Rows in `by_agent` and `by_session`. Clamped to 1–200 |

### Example

```bash theme={null}
curl "https://<your-host>/api/observability/finops/savings?range=7d&scope=agent&limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "window": {
      "start": "2026-11-07T09:00:00Z",
      "end": "2026-11-14T09:00:00Z"
    },
    "total": {
      "saved_tokens": 1840000,
      "saved_input_tokens": 1720000,
      "saved_output_tokens": 120000,
      "saved_cost_usd": 21.4,
      "actual_tokens": 9600000,
      "actual_cost_usd": 112.8,
      "baseline_tokens": 11440000,
      "baseline_cost_usd": 134.2,
      "token_reduction_pct": 16.08,
      "cost_reduction_pct": 15.95,
      "basis": "mixed"
    },
    "by_program": [
      {
        "program": "pacms",
        "label": "Shorter chat history",
        "saved_tokens": 1400000,
        "saved_input_tokens": 1400000,
        "saved_output_tokens": 0,
        "saved_cost_usd": 16.1,
        "actual_tokens": 9600000,
        "actual_cost_usd": 112.8,
        "baseline_tokens": 11000000,
        "baseline_cost_usd": 128.9,
        "token_reduction_pct": 12.73,
        "cost_reduction_pct": 12.49,
        "basis": "measured",
        "layers": [
          {
            "layer": "context_selection",
            "saved_tokens": 1400000,
            "saved_input_tokens": 1400000,
            "saved_output_tokens": 0,
            "saved_cost_usd": 16.1,
            "actual_tokens": 9600000,
            "actual_cost_usd": 112.8,
            "baseline_tokens": 11000000,
            "baseline_cost_usd": 128.9,
            "token_reduction_pct": 12.73,
            "cost_reduction_pct": 12.49,
            "basis": "measured"
          }
        ],
        "by_tier": [
          { "tier": "medium", "saved_tokens": 1400000, "saved_cost_usd": 16.1 }
        ]
      }
    ],
    "by_agent": [
      {
        "agent_id": "6a1f3c2e-8b4d-4f0a-9e21-7c5d3b2a1f00",
        "agent_name": "support-triage",
        "calls": 4210,
        "input_tokens_before": 7300000,
        "input_tokens_after": 6100000,
        "saved_tokens": 1200000,
        "saved_input_tokens": 1200000,
        "saved_output_tokens": 0,
        "saved_cost_usd": 13.9,
        "actual_tokens": 6400000,
        "actual_cost_usd": 74.2,
        "baseline_tokens": 7600000,
        "baseline_cost_usd": 88.1,
        "token_reduction_pct": 15.79,
        "cost_reduction_pct": 15.78,
        "basis": "measured"
      }
    ],
    "by_session": [],
    "coverage": {
      "calls_in_window": 9820,
      "calls_with_any_layer_enabled": 6100,
      "agents_total": 12,
      "agents_optimized": 5,
      "agents_with_compress_enabled": 3,
      "agents_with_minimal_code_enabled": 1,
      "agents_with_prompt_comments": 0,
      "optimized_spend_usd": 74.2,
      "unoptimized_spend_usd": 38.6,
      "top_unoptimized": {
        "agent_id": "c0ffee00-1111-4222-8333-444455556666",
        "agent_name": "report-writer",
        "spend_usd": 21.3
      }
    }
  },
  "status_code": 200,
  "message": "ok"
}
```

### Response fields

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

| Field | Type | Description |
| - | - | - |
| `saved_tokens` | integer | `saved_input_tokens + saved_output_tokens` |
| `saved_input_tokens`, `saved_output_tokens` | integer | Tokens not sent or not generated because of the optimization |
| `saved_cost_usd` | number | Dollars saved |
| `actual_tokens`, `actual_cost_usd` | number | What the traffic actually used and cost |
| `baseline_tokens`, `baseline_cost_usd` | number | Actual plus saved: the estimate without optimizations |
| `token_reduction_pct`, `cost_reduction_pct` | number or null | Saved as a percentage of baseline. `null` when the baseline is zero |
| `basis` | string | How the figure was arrived at. `measured` is a difference the server recorded per call. `seed_default` and `fixture` apply a percentage to counted eligible traffic, for optimizations whose counterfactual can't be observed. `mixed` is a roll-up of both kinds |

**Other fields:**

| Field | Description |
| - | - |
| `window` | The resolved `start` and `end` |
| `by_program[].program` | Stable ID of the optimization program |
| `by_program[].label` | Display name: **Smaller prompts**, **Shorter chat history**, **Less code written**, **Leaner agent instructions**, **Smaller tool lists**, **Smaller injected context**, or **Other** |
| `by_program[].layers` | The individual mechanisms within the program. A layer computed from a percentage includes a `factor` object with the percentage applied, its basis and when it was measured |
| `by_program[].by_tier` | For the chat-history program only: savings per [context budget](https://docs.nasiko.com/tokenops/reduce-cost.md) tier. Omitted when empty |
| `by_program[].note` | Present when a program shows zero or partial savings, explaining why (for example, that no agent has it turned on) |
| `by_agent[]` | Per-agent rows, with `calls`, `input_tokens_before` and `input_tokens_after`. Empty when `scope=session` |
| `by_session[]` | Per-session rows, with `session_id`, `started_at`, `turn_count` and `agent_names`. Empty when `scope=agent` |
| `coverage` | How much of the window's traffic and agents had any optimization on. `top_unoptimized` names the highest-spending agent with none, and is omitted when there isn't one |

### What you see

* A non-superuser sees only agents they can access.

> [!NOTE]
>
> **Plans:** Pro and Enterprise. **Self-hosted:** Enterprise license.

> [!NOTE]
>
> 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

| Status | Body | When |
| - | - | - |
| `400` | `invalid range '<value>' — expected 24h, 7d, or 30d` | Unsupported `range` |
| `400` | `invalid scope '<value>' (expected total\|agent\|session)` | Unsupported `scope` |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `404` | `agent not found` | `agent_id` names no agent, or one you can't access |
| `500` | `internal server error` | Server-side failure |

***

## 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`](https://docs.nasiko.com/reference/cli/observe).

**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

| Name | Type | Description |
| - | - | - |
| `session_id` | string | Chat session ID |

### Example

```bash theme={null}
curl https://<your-host>/api/observability/session/ses_01J9Z3K8XQ/turns \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "turns": [
    {
      "title": "Summarize yesterday's support escalations",
      "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "calls": 3,
      "tokens": 18422,
      "cost_usd": 0.041275,
      "turn_start": "2026-11-14T08:12:03.551Z"
    },
    {
      "title": "Now group them by product area",
      "flow_id": "a1d0c6e83f027327d8461063f4ac58a6",
      "calls": 2,
      "tokens": 9310,
      "cost_usd": 0.019802,
      "turn_start": "2026-11-14T08:14:40.112Z"
    }
  ]
}
```

| Field | Type | Description |
| - | - | - |
| `title` | string or null | The user's message for the turn, when known |
| `flow_id` | string | The turn's ID. It's also the trace ID for that turn |
| `calls` | integer | Model calls made during the turn |
| `tokens` | integer | Total tokens, including cache reads and cache writes |
| `cost_usd` | number | Cost in USD, rounded to six decimals |
| `turn_start` | timestamp | When the turn's first model call started |

Turns are ordered oldest first.

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `500` | `internal error` | Server-side failure |

### 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

| Name | Type | Description |
| - | - | - |
| `session_id` | string | Chat session ID |

### Example

```bash theme={null}
curl https://<your-host>/api/observability/session/ses_01J9Z3K8XQ/tool-calls \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "session_id": "ses_01J9Z3K8XQ",
  "tool_calls": [
    {
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "call_id": "call_8Hk2pQ",
      "agent_name": "support-triage",
      "tool_name": "search_tickets",
      "tool_kind": null,
      "status": "succeeded",
      "error": null,
      "arguments": "{\"query\":\"escalated\",\"since\":\"2026-11-13\"}",
      "output": "[{\"id\":4812,\"subject\":\"Refund delayed\"}]",
      "duration_ms": 412,
      "started_at": "2026-11-14T08:12:05.004Z"
    }
  ]
}
```

| Field | Type | Description |
| - | - | - |
| `trace_id` | string | Trace the call belongs to (one turn) |
| `call_id` | string | The tool call's ID |
| `agent_name` | string | Agent that made the call |
| `tool_name` | string | Tool that was called |
| `tool_kind` | string or null | Kind of tool, when the emitter reported one |
| `status` | string | `succeeded`, `failed`, `unknown`, or the status the emitter reported |
| `error` | string or null | Error message for a failed call |
| `arguments` | string or null | Arguments as a JSON string, when captured |
| `output` | string or null | Tool output as a string, when captured |
| `duration_ms` | integer or null | How long the call took |
| `started_at` | timestamp | When the call started |

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `404` | `session not found` | Unknown or deleted session, or one that isn't yours |
| `500` | Empty body, or `internal error` | Server-side failure |

### 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

| Name | Type | Default | Description |
| - | - | - | - |
| `range` | string | `30d` | `7d`, `30d`, or `90d` |

### Example

```bash theme={null}
curl "https://<your-host>/api/overview/estate?range=30d" \
  -H "Authorization: Bearer $TOKEN"
```

Abbreviated response — each array holds one object per node:

```json theme={null}
{
  "data": {
    "as_of": "2026-11-14T09:00:00Z",
    "days": ["2026-10-16", "2026-10-17", "...", "2026-11-14"],
    "me": "9d2e4f10-3a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "mine": ["6a1f3c2e-8b4d-4f0a-9e21-7c5d3b2a1f00"],
    "groups": [],
    "people": [],
    "workflows": [],
    "routers": [],
    "providers": [],
    "models": [],
    "agents": [],
    "tools": [],
    "harnesses": [],
    "flows": [],
    "problems": [
      {
        "id": "agent-failing:6a1f3c2e-8b4d-4f0a-9e21-7c5d3b2a1f00",
        "kind": "errors",
        "also": null,
        "tier": "worse",
        "title": "support-triage fails 12% of runs",
        "why": "31 of its runs this week ended in an error; whoever called it got no answer.",
        "metric": {
          "label": "Success rate",
          "current": 88.0,
          "target": 95.0,
          "direction": "higher",
          "unit": "%",
          "min": 0.0,
          "max": 100.0
        },
        "trend": [97.1, 96.4, 95.0, 93.2, 90.8, 89.5, 88.0, 87.6, 88.3, 88.0],
        "since": "2026-11-09",
        "confidence": "high",
        "evidence": [
          "31 of 258 checked runs failed in the last 7 days",
          "3% failed the week before"
        ],
        "fixed_when": "Under 5% of runs failing for a day",
        "action": {
          "label": "Open the agent",
          "target": { "page": "agent", "id": "6a1f3c2e-8b4d-4f0a-9e21-7c5d3b2a1f00", "query": null }
        },
        "entities": ["6a1f3c2e-8b4d-4f0a-9e21-7c5d3b2a1f00"],
        "flow_id": "people-agents",
        "count": 31,
        "chain_id": null,
        "owner_id": null,
        "snoozed_until": null,
        "handled_at": null,
        "score": 79.9,
        "mine": true
      }
    ],
    "chains": [],
    "opportunities": [],
    "daily": [],
    "allowance": null
  }
}
```

### Top-level fields

| Field | Description |
| - | - |
| `as_of` | When the estate was computed |
| `days` | The dates in the window |
| `me` | Your user ID |
| `mine` | IDs of the nodes you own or touch |
| `groups` | Always empty |
| `people` | Each person's spend, session count, success rate and segment (`light`, `stuck`, `expensive`, or `value`) |
| `workflows` | Each workflow's owner, run count and steps |
| `routers`, `providers`, `models` | Routing paths, providers with their share of traffic, and models with spend, call count and p95 latency |
| `agents` | Each deployed agent's owner, models, tools, spend, runs, success rate, p95 latency and whether it's idle |
| `tools` | MCP tools, with the connector they come from and when they were turned off, if they were |
| `harnesses` | Coding harnesses with their models, tools and spend |
| `flows` | The connections between the map's cards, with volume and spend. These are map edges, not user request flows |
| `problems` | Problems found, most urgent first. See below |
| `chains` | Cause chains: one root cause linking several problems, with the fix and how many problems it clears |
| `opportunities` | Savings opportunities worth at least \$0.50 a month, with the estimated monthly `saving_usd`, method and effort |
| `daily` | Spend per day as `unbudgeted_usd`, and what optimizations saved as `saved_usd`. `budgeted_usd` and `uncapped_usd` are always `0` |
| `allowance` | Always `null` |

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

| Field | Type | Description |
| - | - | - |
| `id` | string | `<rule>:<entity id>`, for example `agent-failing:<agent id>`. Stable while the problem lasts |
| `kind` | string | `errors`, `slow`, or `cost`. `also` names a second kind when one applies |
| `tier` | string | `broken` or `worse` |
| `title`, `why` | string | One-line summary and explanation |
| `metric` | object | The measure that fired: `label`, `current`, `target`, `direction` (`higher` or `lower` is better), `unit`, `min`, `max` |
| `trend` | number\[] | The metric over the last 10 days |
| `since` | date | When the problem started |
| `confidence` | string | `high` (measured failures) or `medium` (inferred from configuration or timing) |
| `evidence` | string\[] | The numbers the rule fired on |
| `fixed_when` | string | What clears the problem |
| `action` | object | Where to go to fix it: a `label` and a dashboard `target` page |
| `entities` | string\[] | Node the problem is about, then every node it involves |
| `flow_id` | string or null | The map connection the problem sits on |
| `count` | integer | How many events (failed runs, for example) the problem covers |
| `chain_id` | string or null | Cause chain this problem belongs to |
| `owner_id` | UUID or null | Who is on it |
| `snoozed_until` | timestamp or null | Snooze end. `null` once the snooze has passed |
| `handled_at` | timestamp or null | When it was marked handled. Shown only on the UTC day it was marked |
| `score` | number | Urgency. Higher is more urgent |
| `mine` | boolean | `true` when the problem involves a node you own or touch |

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `range must be 7d, 30d or 90d` | Unsupported `range` |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` or `invalid user identity` | No valid session |
| `500` | `internal error` | Server-side failure |

### 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

| Name | Type | Description |
| - | - | - |
| `id` | string | Problem ID from `GET /api/overview/estate`. URL-encode it — it contains `:` |

### Request body

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

| Field | Type | Description |
| - | - | - |
| `owner_id` | UUID or null | Assign the problem to this user. `null` unassigns it |
| `snoozed_until` | timestamp or null | Hide the problem until this time. `null` clears the snooze |
| `handled` | boolean | `true` marks it handled, `false` clears that |

### Example

```bash theme={null}
curl -X PATCH "https://<your-host>/api/overview/problems/agent-failing%3A6a1f3c2e-8b4d-4f0a-9e21-7c5d3b2a1f00" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "snoozed_until": "2026-11-17T09:00:00Z" }'
```

```json theme={null}
{
  "data": {
    "id": "agent-failing:6a1f3c2e-8b4d-4f0a-9e21-7c5d3b2a1f00",
    "kind": "errors",
    "tier": "worse",
    "title": "support-triage fails 12% of runs",
    "owner_id": null,
    "snoozed_until": "2026-11-17T09:00:00Z",
    "handled_at": null,
    "score": 79.9,
    "mine": true
  }
}
```

The response carries the full problem object; fields are trimmed here for space. See [Problem fields](#problem-fields).

### Errors

| Status | Body | When |
| - | - | - |
| `400` | Plain-text JSON parse error | Body isn't valid JSON |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `404` | `no such problem` | No current problem with this ID in your estate |
| `415` | Plain text | `Content-Type: application/json` is missing |
| `422` | `send exactly one of owner_id, snoozed_until or handled` | None or more than one field sent |
| `422` | `no such person` | `owner_id` isn't an existing user |
| `422` | Plain-text deserialization error | Unknown field or wrong field type |
| `500` | `internal error` | Server-side failure |

### 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.

## Related

* [TokenOps dashboard](https://docs.nasiko.com/tokenops/dashboard.md)
* [Reduce cost](https://docs.nasiko.com/tokenops/reduce-cost.md)
* [Cost attribution](https://docs.nasiko.com/tokenops/attribution.md)
* [Sessions and traces](https://docs.nasiko.com/dashboard/sessions-and-traces.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.