> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/ai-gateway/session/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Session

Sessions group related gateway requests and agent runs into one user journey, workflow execution, or multi-step task.

Use sessions when a single business interaction includes multiple model calls, tool calls, retries, or agent runs. A support conversation, n8n workflow execution, research job, or paid endpoint call can all be represented as sessions.

## Session vs Run vs Request

| Concept | Scope                                   | Example                                                        |
| ------- | --------------------------------------- | -------------------------------------------------------------- |
| Session | Broader interaction or workflow context | One support case, workflow execution, or customer conversation |
| Run     | One agent task inside the session       | Classify ticket, draft reply, verify refund eligibility        |
| Request | One gateway model request               | A single `/v1/chat/completions` call                           |

Use one session ID across related runs. Use a new run ID for each task. Use a unique request ID for each gateway request.

## Recommended Headers

| Header                  | Purpose                                           |
| ----------------------- | ------------------------------------------------- |
| `alephant-session-id`   | Groups related requests and runs into one session |
| `alephant-session-name` | Human-readable session label                      |
| `alephant-session-path` | Optional workflow or route path                   |
| `Alephant-Agent-Id`     | Stable Alephant agent identity                    |
| `Alephant-Run-Id`       | One task execution inside the session             |
| `x-request-id`          | One request-level identifier                      |

Example:

```bash
curl https://ai.alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "alephant-session-id: sess_customer_123_support_20260609" \
  -H "alephant-session-name: support ticket 8421" \
  -H "alephant-session-path: /support/triage" \
  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Classify this support ticket." }
    ]
  }'
```

## Session Analytics

Session analytics helps answer:

* Which sessions are active, completed, or intercepted?
* Which agents and workflows created the most session cost?
* Which sessions contain policy events?
* Which sessions had high latency, repeated retries, or unusual token usage?
* Which session steps contributed to total cost?

The lower-level Analytics API includes session endpoints for session lists, vitals, and session detail. Use the API Reference for exact parameters and response shapes.

## Implementation Pattern

1. Generate or load a stable session ID when the conversation, workflow, or job starts.
2. Generate a new Run ID for each agent task inside the session.
3. Send `alephant-session-id`, `Alephant-Agent-Id`, and `Alephant-Run-Id` with every gateway request.
4. Send `x-request-id` for each individual request when your application can generate one.
5. Query logs, analytics, or session detail views to inspect cost, policy events, and execution steps.

## Related Pages

* [Agent IDs And Run IDs](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds)
* [Agent Run Tracing](/docs/overview/core-concepts/agent-run-tracing)
* [Gateway Integration](/docs/overview/core-concepts/gateway-integration)