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

# Flows API

> List and inspect flows — one user request as it moves across agents — and record flows and steps from your own agents.

A **flow** is the lifecycle of one user request: the message that starts it, every agent call it fans out into, and how it ends. A flow's `flow_id` is the request's W3C trace ID — the same ID in the `traceparent` header and in the session trace. It's also the scope of the [flow limits](https://docs.nasiko.com/governance/flow-limits.md#the-flow-guard): call depth, fan-out, token budget, and wall-clock timeout all count against one `flow_id`.

Nasiko records a flow automatically when you chat with an agent, use the orchestrator, or run a [workflow](https://docs.nasiko.com/build/workflows.md). The dashboard's **Flows** screen ([Flows](https://docs.nasiko.com/dashboard/sessions-and-traces.md#flows)) and the agent activity in **Chat** read these routes. The `POST` routes let an agent or integration record its own flow and steps.

Not in the generated OpenAPI spec.

## Authentication

Every route takes the session JWT from `POST /api/auth/login` as `Authorization: Bearer <token>`, or the dashboard session cookie. Any authenticated user can call them; there is no role requirement and no rate limit.

| Route | Who sees what |
| - | - |
| `GET /api/flows` | Only your own flows, superuser included |
| `GET /api/flows/{flow_id}`, `GET`/`POST /api/flows/{flow_id}/steps` | Your own flows. A superuser can read and add steps to any user's flow |
| `POST /api/flows` | Creates a flow owned by you |

A flow you can't see returns `404`, the same as one that doesn't exist.

A missing or invalid credential returns `401` before the handler runs:

```json theme={null}
{ "data": null, "status_code": 401, "message": "missing or invalid token" }
```

Handler errors return a plain-text body (or an empty body for `404`).

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/flows` | List your flows, newest first |
| `POST` | `/api/flows` | Record a new flow |
| `GET` | `/api/flows/{flow_id}` | One flow with its steps |
| `GET` | `/api/flows/{flow_id}/steps` | A flow's steps |
| `POST` | `/api/flows/{flow_id}/steps` | Record a step |

## The flow object

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Record ID |
| `flow_id` | string | The flow's trace ID. Use it in every other route |
| `user_id` | UUID | The user the flow belongs to |
| `root_agent_id` | UUID \| null | The agent the request started at |
| `root_agent_name` | string \| null | That agent's name |
| `title` | string \| null | What started the flow — usually the user's message |
| `status` | string | `running`, `paused` (waiting on a [human approval](https://docs.nasiko.com/api-reference/approvals.md)), `completed`, or `failed` |
| `max_depth_reached` | integer | Deepest agent-to-agent call depth recorded |
| `total_invocations` | integer | Agent invocations recorded |
| `total_tokens_used` | integer | Tokens recorded on the flow |
| `total_cost_usd` | string \| null | Cost recorded on the flow, as a decimal string |
| `duration_ms` | integer \| null | Wall-clock duration, set when the flow ends |
| `error_message` | string \| null | Why the flow failed |
| `metadata` | object | Free-form JSON. Chat flows carry `context_id` (the conversation); workflow flows carry `mode: "free_flowing"` |
| `created_at` | timestamp | When the flow started |
| `completed_at` | timestamp \| null | When it ended |

For token and cost reporting by agent, model, and team, use [TokenOps](https://docs.nasiko.com/tokenops/dashboard.md).

## The step object

A step is one agent call inside the flow.

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Step ID |
| `flow_id` | string | The flow it belongs to |
| `step_order` | integer | Position in the flow, starting at `1` |
| `depth` | integer | Call depth. `0` is the root agent; each agent-to-agent hop adds one |
| `agent_id` | UUID \| null | The agent called |
| `agent_name` | string | That agent's name |
| `caller_agent_name` | string \| null | The agent that made the call. `null` for a call from the user |
| `input_summary` | string \| null | A preview of what was sent |
| `output_summary` | string \| null | A preview of what came back |
| `status` | string | `pending`, `running`, `completed`, `failed`, `awaiting_human`, or `resumed` |
| `tokens_used` | integer | Tokens recorded for the step |
| `latency_ms` | integer \| null | How long the call took |
| `error_message` | string \| null | Why the step failed |
| `created_at` | timestamp | When the call started |
| `completed_at` | timestamp \| null | When it ended |

## List flows

`GET /api/flows`

Returns your flows, newest first. Use it to build a flow list, or to find flows paused on a human with `status=paused` — the dashboard's overview does exactly that.

**Auth:** session JWT or dashboard cookie. Returns only the caller's flows.

### Query parameters

| Name | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `50` | Page size |
| `offset` | integer | `0` | Rows to skip |
| `status` | string | — | Exact match: `running`, `paused`, `completed`, or `failed` |
| `q` | string | — | Case-insensitive substring match on `root_agent_name` or `title` |

### Example

```bash theme={null}
curl "https://<your-host>/api/flows?status=paused&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "id": "5a1f0c3e-7b42-4d9a-8e16-2c4b6d8f0a13",
      "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "user_id": "9e2d7c41-1f3a-4b6e-a8d5-0c7b2e9f4a61",
      "root_agent_id": "c1e4a9f0-3b27-4d58-8e6a-91f2d0b7c3a4",
      "root_agent_name": "triage-agent",
      "title": "Open an issue for the failing build",
      "status": "paused",
      "max_depth_reached": 1,
      "total_invocations": 2,
      "total_tokens_used": 0,
      "total_cost_usd": null,
      "duration_ms": null,
      "error_message": null,
      "metadata": { "context_id": "ctx-5d2e81" },
      "created_at": "2026-11-14T09:13:55Z",
      "completed_at": null
    }
  ],
  "total": 1
}
```

### Pagination

`total` is the number of flows on **this page**, not the total across all pages. Page with `limit` and `offset`; a page with fewer than `limit` rows is the last one.

### Errors

| Status | Body | When |
| - | - | - |
| `400` | plain text | `limit` or `offset` isn't an integer |
| `401` | JSON `{ "data", "status_code", "message" }` | Missing, expired, or invalid credential |
| `500` | `internal error` | Server error |

## Record a flow

`POST /api/flows`

Creates a flow owned by you, in status `running`. Use it when your own agent or integration starts a request and you want it in the **Flows** screen. Chat, the orchestrator, and workflows record their flows for you — don't call this for those.

Recording a flow doesn't change the [flow limits](https://docs.nasiko.com/governance/flow-limits.md#the-flow-guard). They apply to every agent-to-agent call with that trace ID either way.

**Auth:** session JWT or dashboard cookie. Any authenticated user.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `flow_id` | string | Yes | The request's trace ID (the trace-id part of its `traceparent`). Must be unique |
| `root_agent_id` | UUID | No | The agent the request starts at. Must be an existing agent |
| `root_agent_name` | string | No | That agent's name, for display |
| `title` | string | No | What started the flow, for display and `q` search |
| `metadata` | object | No | Free-form JSON. Defaults to `{}` |
| `session_id` | string | No | The chat session this request belongs to. Defaults to `flow_id` |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/flows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "root_agent_name": "triage-agent",
    "title": "Open an issue for the failing build",
    "metadata": { "source": "ci-bot" }
  }'
```

Returns `201 Created` with the new flow:

```json theme={null}
{
  "id": "5a1f0c3e-7b42-4d9a-8e16-2c4b6d8f0a13",
  "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "user_id": "9e2d7c41-1f3a-4b6e-a8d5-0c7b2e9f4a61",
  "root_agent_id": null,
  "root_agent_name": "triage-agent",
  "title": "Open an issue for the failing build",
  "status": "running",
  "max_depth_reached": 0,
  "total_invocations": 0,
  "total_tokens_used": 0,
  "total_cost_usd": null,
  "duration_ms": null,
  "error_message": null,
  "metadata": { "source": "ci-bot" },
  "created_at": "2026-11-14T09:13:55Z",
  "completed_at": null
}
```

### Behavior

* Not idempotent. A second call with the same `flow_id` returns `409`.
* You can't claim another user's request: a `session_id` that belongs to another user's chat or flows, or a `flow_id` that already has another user's usage or tool calls recorded, returns `403`.

### Errors

| Status | Body | When |
| - | - | - |
| `400`, `415`, `422` | plain text | Body isn't valid JSON, has no `Content-Type: application/json`, `flow_id` is missing, or a field has the wrong type |
| `401` | JSON `{ "data", "status_code", "message" }` | Missing, expired, or invalid credential |
| `403` | `session belongs to another user` | `session_id` is another user's |
| `403` | `trace belongs to another user` | `flow_id` already carries another user's activity |
| `409` | `flow already exists or invalid reference` | `flow_id` is taken, or `root_agent_id` isn't an existing agent |
| `500` | `internal error` | Server error |

## Get a flow

`GET /api/flows/{flow_id}`

Returns one flow and all its steps in order. This backs the flow detail page and the "agents used" list under a routed reply in **Chat**. Use it after a request finishes to see which agents ran, in what order, and where it failed.

**Auth:** session JWT or dashboard cookie. Owner or superuser.

### Path parameters

| Name | Type | Description |
| - | - | - |
| `flow_id` | string | The flow's trace ID |

### Example

```bash theme={null}
curl https://<your-host>/api/flows/4bf92f3577b34da6a3ce929d0e0e4736 \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "flow": {
    "id": "5a1f0c3e-7b42-4d9a-8e16-2c4b6d8f0a13",
    "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "user_id": "9e2d7c41-1f3a-4b6e-a8d5-0c7b2e9f4a61",
    "root_agent_id": "c1e4a9f0-3b27-4d58-8e6a-91f2d0b7c3a4",
    "root_agent_name": "triage-agent",
    "title": "Open an issue for the failing build",
    "status": "completed",
    "max_depth_reached": 1,
    "total_invocations": 2,
    "total_tokens_used": 0,
    "total_cost_usd": null,
    "duration_ms": 8000,
    "error_message": null,
    "metadata": { "context_id": "ctx-5d2e81" },
    "created_at": "2026-11-14T09:13:55Z",
    "completed_at": "2026-11-14T09:14:03Z"
  },
  "steps": [
    {
      "id": "b7c2e4a1-5d3f-4e8b-9a60-1c2d3e4f5a6b",
      "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "step_order": 1,
      "depth": 0,
      "agent_id": "c1e4a9f0-3b27-4d58-8e6a-91f2d0b7c3a4",
      "agent_name": "triage-agent",
      "caller_agent_name": null,
      "input_summary": "Open an issue for the failing build",
      "output_summary": "Created issue #482",
      "status": "completed",
      "tokens_used": 0,
      "latency_ms": 7000,
      "error_message": null,
      "created_at": "2026-11-14T09:13:56Z",
      "completed_at": "2026-11-14T09:14:03Z"
    }
  ]
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | JSON `{ "data", "status_code", "message" }` | Missing, expired, or invalid credential |
| `404` | empty | No flow with this ID, or it isn't yours |
| `500` | `internal error` | Server error |

## List a flow's steps

`GET /api/flows/{flow_id}/steps`

Returns just the steps of one flow, ordered by `step_order`, as a bare JSON array. Use it when you already have the flow and only need its timeline.

**Auth:** session JWT or dashboard cookie. Owner or superuser.

### Path parameters

| Name | Type | Description |
| - | - | - |
| `flow_id` | string | The flow's trace ID |

### Example

```bash theme={null}
curl https://<your-host>/api/flows/4bf92f3577b34da6a3ce929d0e0e4736/steps \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
[
  {
    "id": "b7c2e4a1-5d3f-4e8b-9a60-1c2d3e4f5a6b",
    "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "step_order": 1,
    "depth": 0,
    "agent_id": "c1e4a9f0-3b27-4d58-8e6a-91f2d0b7c3a4",
    "agent_name": "triage-agent",
    "caller_agent_name": null,
    "input_summary": "Open an issue for the failing build",
    "output_summary": "Created issue #482",
    "status": "completed",
    "tokens_used": 0,
    "latency_ms": 7000,
    "error_message": null,
    "created_at": "2026-11-14T09:13:56Z",
    "completed_at": "2026-11-14T09:14:03Z"
  }
]
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | JSON `{ "data", "status_code", "message" }` | Missing, expired, or invalid credential |
| `404` | empty | No flow with this ID, or it isn't yours |
| `500` | `internal error` | Server error |

## Record a step

`POST /api/flows/{flow_id}/steps`

Appends a step to a flow you recorded, in status `running`. Nasiko assigns the next `step_order`. Use it from your own agent or integration each time it calls another agent, so the call shows on the flow's timeline.

**Auth:** session JWT or dashboard cookie. Owner or superuser.

### Path parameters

| Name | Type | Description |
| - | - | - |
| `flow_id` | string | The flow's trace ID |

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `agent_name` | string | Yes | The agent being called |
| `agent_id` | UUID | No | Its ID. Must be an existing agent |
| `caller_agent_name` | string | No | The agent making the call. Omit for a call from the user |
| `depth` | integer | No | Call depth. Defaults to `0` |
| `input_summary` | string | No | A preview of what was sent |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/flows/4bf92f3577b34da6a3ce929d0e0e4736/steps \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "github-agent",
    "caller_agent_name": "triage-agent",
    "depth": 1,
    "input_summary": "Create an issue: build #9123 failing on main"
  }'
```

Returns `201 Created` with the new step:

```json theme={null}
{
  "id": "d4e5f6a7-8b9c-4d0e-a1f2-3b4c5d6e7f80",
  "flow_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "step_order": 2,
  "depth": 1,
  "agent_id": null,
  "agent_name": "github-agent",
  "caller_agent_name": "triage-agent",
  "input_summary": "Create an issue: build #9123 failing on main",
  "output_summary": null,
  "status": "running",
  "tokens_used": 0,
  "latency_ms": null,
  "error_message": null,
  "created_at": "2026-11-14T09:13:58Z",
  "completed_at": null
}
```

### Behavior

* Not idempotent. Each call appends a new step.
* A recorded step is for display. The [flow guard](https://docs.nasiko.com/governance/flow-limits.md#the-flow-guard) counts depth and fan-out from the actual agent calls Nasiko makes, not from steps you record.

### Errors

| Status | Body | When |
| - | - | - |
| `400`, `415`, `422` | plain text | Body isn't valid JSON, has no `Content-Type: application/json`, `agent_name` is missing, or a field has the wrong type |
| `401` | JSON `{ "data", "status_code", "message" }` | Missing, expired, or invalid credential |
| `404` | empty | No flow with this ID, or it isn't yours |
| `500` | `internal error` | Server error, including an `agent_id` that isn't an existing agent |


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