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

# Sessions

> See every prompt, tool call and decision, with the rule that fired.

See every prompt, tool call and decision your agents made, with the rule that fired. Each request to an agent becomes a turn in a session you can read step by step.

For example, a user asks your agent to delete a database. The session shows the turn, a **Blocked** decision from the policy `no-delete-database`, and that no model was called. Your app received a refusal with `X-Xenovia-Decision: blocked`.

![Session timeline with a restricted\_data policy step selected, showing it was Blocked and the client got 200](https://mintcdn.com/xenovia/RO5UF1Tk8L9B7yPt/images/screens/sessions-blocked-turn.png?fit=max\&auto=format\&n=RO5UF1Tk8L9B7yPt\&q=85\&s=75ebcc513c425ba37830ac7f8a8c916b)

A session open on a blocked turn

Every request to an agent and every SDK check that passes validation and authentication produces a **turn**, grouped under a **session**. A turn holds its **runs**: the model call, the policy and [Neon](https://docs.xenovia.io/control/neon.md) checks, and any escalation. The **Sessions** page lists them.

## The Sessions page

Each session in the list shows its agent, turns, tokens and outcome, and where it is:

| State | Meaning |
| - | - |
| **Running** | The session is still receiving calls |
| **Waiting for approval** | It has an open [escalation](https://docs.xenovia.io/control/policies.md#escalations) |
| **Ended** | Nothing is in progress |

Filter by agent, outcome, state, [sub-agent](https://docs.xenovia.io/agents/sub-agents.md) or time, or search by session ID, session name or agent name. The list refreshes on its own.

Open a session to read it turn by turn, or as a **Timeline**. While the session is running, the page shows **Live** and refreshes every few seconds. Each turn shows its steps:

* The model call, with its **Model time** and, for a stream, **Time to first token**.
* A **Neon** step for each stage Neon judged, with **What Neon found** and **Explain this decision**.
* Each policy decision, tool call and escalation.
* For a call made with a sub-agent key, a **Sub-agent** label. A linked call shows who called it under **Called by**.

### Provider requests and responses

For a failed provider call, the step also keeps exactly what was sent to the provider and what it answered. Choose **View provider request and response** to see them. Headers are never kept.

To keep them for every model call, an organization admin can turn on **Keep provider requests and responses** on the agent's **Overview** for 1, 4 or 24 hours. What it keeps is stored for 30 days.

## What a turn records

`GET /api/v1/traces` returns trace records: one for each run, plus one for the turn as a whole (`step_type` is `request_finished`).

> [accordion] Every trace field
>
> | Field | Description |
> | - | - |
> | `trace_id` | The record's ID: the run's, or the turn's on the turn record |
> | `trace_flow_id` | The turn the record belongs to |
> | `session_id` / `session_turn` | The session, and the turn's number within it |
> | `step_type` | The kind of run: `llm` for the model call, `llm_attempt` for a failed [fallback](https://docs.xenovia.io/providers/fallbacks.md) attempt, `policy`, `guardrail` for a Neon check, `escalation`, `tool`, or `request_finished` |
> | `agent_id` / `org_id` | Agent and organization |
> | `provider` / `model` | The upstream provider and the model the runtime called |
> | `request_tokens` / `response_tokens` | Input and output tokens |
> | `latency_ms` | The run's duration; on the turn record, the whole request |
> | `ttft_ms` | Time to first token (streaming) |
> | `governance_latency_ms` / `model_latency_ms` | On the turn record: the time its checks added, and the provider's time |
> | `policy_decision` / `policy_rule` | The policy action and the rule that fired |
> | `guardrail_name` / `guardrail_decision` / `guardrail_reason` | On a Neon run: what it checked and decided |
> | `final_decision` | On the turn record: `allowed`, `blocked`, `escalated` or `error` |
> | `status_code` | The HTTP status of the request |
> | `custom_properties` | Key–value pairs from `X-Xenovia-Property-*` headers |
> | `sub_agent` / `caller_agent_id` / `caller_sub_agent` / `agent_depth` | Who made the call (see [Sub-agents](https://docs.xenovia.io/agents/sub-agents.md#sessions-and-traces)) |
> | `workflow_id` / `parent_trace_id` | Cross-request linkage from the headers below |

Client-executed tool calls are not runs. They appear in the model run's output and, once your app returns them, in the next turn's messages. Tools a coding agent runs through its hooks are recorded as `tool` runs (see [How tools are checked](https://docs.xenovia.io/control/hosted-tools.md#coding-agents)).

## Enriching a turn

Attach these headers to any request to the agent endpoint:

```python theme={null}
client = OpenAI(
    api_key=os.environ["XENOVIA_API_KEY"],
    base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_AGENT_ID']}/v1",
    default_headers={
        # Group related calls under one session (a valid UUID)
        "X-Xenovia-Session-Id": "550e8400-e29b-41d4-a716-446655440000",
        # Tag the turn with business context
        "X-Xenovia-Property-user-tier": "enterprise",
        "X-Xenovia-Property-feature": "document-summary",
    }
)
```

**Custom property rules:**

* At most 20 properties per request; extras are dropped silently.
* Property names are lowercased; keep them to 64 characters or fewer.
* Values are truncated to 512 bytes.
* Names beginning `policy_` are reserved and dropped.
* A property that breaks a rule is skipped without an error, so confirm important tags appear on the trace.

For cross-request linkage:

| Header | Effect |
| - | - |
| `X-Xenovia-Trace-Flow-Id` | Names the turn. Requests that send the same value are recorded as one turn. Without it, a request with a session is numbered within the session |
| `X-Xenovia-Parent-Trace-Id` | Sets the run's parent |
| `X-Xenovia-Workflow-Id` | Groups turns from several agents and sessions into one workflow. Policies see earlier decisions of the workflow in `input.workflow_context` |

> [!NOTE]
>
> `X-Xenovia-Session-Path` is not currently read by the runtime. Use `X-Xenovia-Session-Id` for grouping and `X-Xenovia-Property-*` for filtering.

## What a block looks like to your app

A blocked call doesn't fail. A policy block, a [Neon](https://docs.xenovia.io/control/neon.md) block, and a policy escalation don't return an error. The runtime answers `200` with a refusal in the format of the API you called. The refusal text is `I can't help with that request.`, and the reply reports no token usage.

| Route | Refusal |
| - | - |
| Chat Completions | `finish_reason: "content_filter"`, with the text as the message's `content` and `refusal` |
| Responses | `status: "incomplete"`, `incomplete_details.reason: "content_filter"`, and a `refusal` content part with the text |
| Messages | `stop_reason: "refusal"`, with the text in a text block |

A blocked reply or tool call is first sent back to the model once, with a note that part of its answer was blocked, so it can answer another way. The note never names the policy or check. The answer then carries `X-Xenovia-Retried: true`: the retry's reply if it passes, or the refusal if it doesn't. A blocked request is refused at once, without a retry.

A Neon escalation, such as a guardrail whose action is `escalate`, doesn't block: the call goes on and the escalation is recorded.

The body never says why a call was blocked. The response headers do:

| Header | Value |
| - | - |
| `X-Xenovia-Decision` | `allowed`, `blocked`, or `unchecked` |
| `X-Xenovia-Reason` | Why the call was blocked or unchecked, such as `policy:<rule>`. Only on `blocked` and `unchecked` |
| `X-Xenovia-Decision-Id` | The Neon decision, when Neon decided. Pass it to `POST /api/v1/agents/{agent_id}/neon/decisions/{decision_id}/explain` for Neon's explanation |
| `X-Xenovia-Retried` | `true` when a blocked reply or tool call was retried |

`X-Xenovia-Trace-Id` identifies the trace. Look it up in the platform to see the full decision.

`unchecked` means Neon couldn't evaluate a stage on which nothing is enforced, so the call went on without a verdict. When Neon can't evaluate a stage that has an enforced check, the runtime fails closed instead: it answers `503` with `Retry-After: 5` and a `service_unavailable` error (`api_error` on Messages). At the request stage, this happens before anything is sent to the provider.

Only the steps of a [simulation](https://docs.xenovia.io/simulation.md) run still get a `403` for a block.

Errors are for requests that can't be answered at all: a bad key is a `401`, an exhausted allowance is a `402`, and a check that can't be evaluated while something on its stage is enforced is a `503` with `Retry-After`. See [Errors](https://docs.xenovia.io/reference/errors.md).

## Response headers

Every response includes:

| Header | Value |
| - | - |
| `X-Xenovia-Session-Id` | Resolved session UUID |
| `X-Xenovia-Trace-Id` | Per-request UUID |
| `X-Xenovia-Decision` | `allowed`, `blocked` or `unchecked` |

Log `X-Xenovia-Session-Id` and `X-Xenovia-Trace-Id` with each call, and open the session in the platform to find it. A blocked call also carries `X-Xenovia-Reason`, and a call Neon decided carries `X-Xenovia-Decision-Id` (see [What a block looks like to your app](#what-a-block-looks-like-to-your-app)). A malformed `X-Xenovia-Session-Id` request header is rejected with `400`.

## Investigating

**1. Notice**

Watch the Sessions view for a rise in blocks or a spike in escalations. Configure alert rules, for example on the **Policy escalation** or **Guardrail escalation** trigger, to be told rather than to poll.

**2. Drill in**

Open a session and read its turns. Each turn carries the messages, tools, model, tokens, decisions and custom properties, so the cause is visible without stitching logs together. On a Neon step, choose **Explain this decision**.

**3. Adjust**

Update the Rego policy, the agent's Neon settings or guardrails, or revoke an agent key. Configuration changes reach the runtime within about five minutes.

**4. Confirm**

Send the request again and check the new turn. Earlier turns keep the decisions they were made with, so they remain as evidence after a change.

> [!NOTE]
>
> Open escalations are listed under **Escalations** in Sessions. Resolving one records the reviewer's note; it does not replay or release the original request.

## Querying traces programmatically

The [management API](https://docs.xenovia.io/api-reference/introduction.md) exposes sessions, turns, runs, aggregate stats, escalations and multi-agent workflows:

> [accordion] Sessions and traces endpoints
>
> | Endpoint | Returns |
> | - | - |
> | `GET /api/v1/sessions` | Sessions, filtered by `agent_id`, `status`, `state`, `sub_agent`, `search`, `from` and `to` |
> | `GET /api/v1/sessions/{session_id}` | One session with its turns and steps. For a long session, only a window of turns carries steps (`windowed` is `true`); pick it with `turn_from` and `turn_to` |
> | `GET /api/v1/sessions/{session_id}/turns?from=&to=` | A range of turns with their steps. `whole=true` includes every step of a long request |
> | `GET /api/v1/traces` | Trace records, filtered by `agent_id`, `session_id`, `trace_flow_id`, `step_type`, `decision`, `provider`, `from` and `to`, and by any custom property as `cp_<key>=<value>` |
> | `GET /api/v1/traces/stats`, `/traces/overview` | Totals and per-interval counts |
> | `GET /api/v1/traces/{trace_id}/runs/{run_id}/content` | A run's whole request, reply and system prompt, when a long session's read left them out |
> | `GET /api/v1/traces/{trace_id}/runs/{run_id}/payload` | The kept provider request and response of a run. `404` when none was kept |
> | `GET /api/v1/workflows`, `/workflows/{workflow_id}` | Workflows and their turns across agents |
> | `GET /api/v1/escalations` | Escalations, filtered by `status` (`open` or `resolved`) |

## What next?

> [card] [Alerts](https://docs.xenovia.io/observability/alerts.md)
>
> Be told when something is blocked or escalated.

> [card] [Policies](https://docs.xenovia.io/control/policies.md)
>
> Adjust the rule that fired.

> [card] [Errors](https://docs.xenovia.io/reference/errors.md)
>
> What each runtime status means.


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