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

# Sessions

> How Wardin groups requests into sessions so "cost per task" is a real metric, not noise.

Agentic clients fan a single piece of work into a storm of API calls — one Claude Code task can emit hundreds of tool-call requests. Per-request metrics are meaningless at that granularity: the number you actually want is **cost per task**. Sessions are how Wardin produces it.

## How grouping works

Every request gets a `session_id`, one of two ways:

1. **Explicit** — send an `X-Wardin-Session-Id` header and it is trusted as-is. Use this when your client knows its own task boundary (a CI job ID, a ticket number, an agent run ID).
2. **Automatic** — without the header, the gateway buckets consecutive requests from the same virtual key using an **idle-timeout window (30 minutes, sliding)**. Each request extends the window; a gap longer than the window starts a new session.

```bash theme={null}
# Explicit session for a CI job
curl https://gw.wardin.ai/v1/messages \
  -H "Authorization: Bearer wardin_sk_CI_KEY" \
  -H "X-Wardin-Session-Id: deploy-frontend-#4812" \
  ...
```

For Claude Code, set it via the custom-headers convention:

```bash theme={null}
export ANTHROPIC_CUSTOM_HEADERS="X-Wardin-Session-Id: my-task-$(date +%s)"
```

<Note>
  Wardin deliberately ignores agentic clients' own per-spawn attribution headers —
  those are ephemeral process IDs, not identity. Attribution always comes from the
  virtual key; sessions only group that key's requests in time.
</Note>

## What a session gives you

* **Cost per task** — total spend across every request in the session, with the split token accounting (input / output / cache-creation / cache-read) intact
* **Request count and duration** — how much traffic one task actually generated
* **Model mix** — which models the task used

## Where sessions appear

* **MY LANE** — each developer's own sessions with per-session cost
* **Analytics API** — `GET /v1/analytics/sessions` for programmatic access

## Sessions and pricing

Because one task can be one request (a chat message) or a thousand (an agent), Wardin treats the **session** as the honest unit of work. If you're comparing costs across tools or teams, compare cost per session — raw request counts punish exactly the agentic workflows that deliver the most value.