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

# Agent Run Tracing

> Trace model calls, tool calls, workflow steps, policy decisions, cost, and revenue across agent runs

Agent run tracing connects individual AI requests to the larger task they belong to.

Request logs are useful, but production agents often execute multi-step work: a model call, a tool call, a retry, a workflow branch, a policy decision, and sometimes a payment event. Alephant treats that activity as a run so teams can understand what happened end to end.

## Trace Model

| Object      | Purpose                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| Workspace   | Top-level tenant and billing boundary                                              |
| Department  | Organizational scope for budgets, members, and policy overrides                    |
| Agent       | Governed identity for an application, service, workflow, or autonomous agent       |
| Virtual Key | Scoped credential used to route traffic and attribute usage                        |
| Session     | A series of related interactions or workflow steps                                 |
| Run         | One execution of an agent task or workflow                                         |
| Step        | A model call, tool call, API call, payment event, policy check, or workflow action |
| Request     | The provider-compatible LLM request routed through Alephant Gateway                |

## What A Run Can Include

A run trace can include:

* Model calls and selected providers
* Tool calls and external API calls
* Workflow steps and branch outcomes
* Prompt template IDs and versions
* Token usage, latency, errors, and retry behavior
* Policy decisions such as allowed, blocked, throttled, or escalated
* Budget consumption and remaining budget context
* Paid endpoint payment events, revenue, and margin data
* Audit events for security and compliance review

## Tracking Headers

Gateway requests can include optional headers that help Alephant group requests into sessions and runs:

| Header                  | Purpose                                                                   |
| ----------------------- | ------------------------------------------------------------------------- |
| `x-request-id`          | Stable request identifier for idempotency and log lookup                  |
| `Alephant-Agent-Id`     | Stable Alephant agent ID for agent run attribution                        |
| `Alephant-Run-Id`       | One task execution ID, reused across all model/tool calls in the same run |
| `alephant-session-id`   | Groups multiple requests into one session                                 |
| `alephant-session-path` | Records a workflow or route path                                          |
| `alephant-session-name` | Human-readable session label                                              |
| `alephant-property-*`   | Custom metadata for filtering and attribution                             |
| `alephant-prompt-id`    | Associates usage with a prompt template                                   |

Use these headers when an application, framework, or workflow engine already knows the task context. If no session headers are present, Alephant still records request-level metadata for the Virtual Key.

For a detailed setup guide with curl, TypeScript, Python, and n8n examples, see [Agent IDs And Run IDs](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds).

## Common Questions

### Why not just use request logs?

Request logs show individual model calls. Run tracing explains the larger execution context: which agent acted, which workflow step created the call, which policy decision applied, and how the total run cost was built.

### What is the difference between a session and a run?

A session is a broader interaction or workflow context. A run is one execution inside that context. For example, a support automation session can include several agent runs, tool calls, and follow-up model requests.

### How does this connect to cost?

Each step can contribute model cost, tool cost, payment cost, or revenue. Alephant rolls those signals up to agents, workflows, sessions, departments, and workspaces.

## Related Pages

* [Agent Gateway](/docs/overview/core-concepts/agent-gateway)
* [Audit & Logs](/docs/overview/security-compliance/audit-logs)
* [Cost Analytics](/docs/overview/fin-ops-budget/cost-analytics)
* [Agent Finance](/docs/overview/fin-ops-budget/agent-finance)