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

# Session Aggregations

> Reserved session metadata fields that HoneyHive automatically calculates

HoneyHive automatically aggregates metrics from child spans to the session level. These fields are **reserved** and will be overwritten if you set them manually.

## Reserved Session Fields

| Field                        | Description                                                   |
| ---------------------------- | ------------------------------------------------------------- |
| `metadata.num_events`        | Total events in the session                                   |
| `metadata.num_model_events`  | Number of model (LLM) events                                  |
| `metadata.has_feedback`      | Whether any event has feedback                                |
| `metadata.cost`              | Total LLM cost (from provider pricing)                        |
| `metadata.total_tokens`      | Total tokens (prompt + completion)                            |
| `metadata.prompt_tokens`     | Input tokens                                                  |
| `metadata.completion_tokens` | Output tokens                                                 |
| `start_time`                 | Earliest `start_time` of any event                            |
| `end_time`                   | Latest `end_time` of any event                                |
| `duration`                   | Calculated from `end_time - start_time` (unless manually set) |

### Token and cost tracking

HoneyHive automatically rolls up token counts and cost from every `model` event in a session.

| Session Field                | Aggregation                                                               |
| ---------------------------- | ------------------------------------------------------------------------- |
| `metadata.total_tokens`      | Sum of `prompt_tokens + completion_tokens` across all model events        |
| `metadata.prompt_tokens`     | Sum of input tokens across all model events                               |
| `metadata.completion_tokens` | Sum of output tokens across all model events                              |
| `metadata.cost`              | Sum of per-call cost, calculated from provider pricing for the model used |

Token counts are extracted from the LLM provider's response (e.g. OpenAI's `usage` field). Cost is calculated server-side using up-to-date pricing tables for each model. If a session contains multiple LLM calls (e.g. a chain or agent loop), all calls are summed at the session level.

You can use these fields to filter, alert, and chart in the HoneyHive dashboard - for example, flagging sessions where `cost > 0.10` or `total_tokens > 10000`.

## Duration Calculation

Duration is calculated as `max(end_time) - min(start_time)` across all events in the session. This works for both synchronous and asynchronous execution:

<Frame>
  <img src="https://mintcdn.com/honeyhiveai/oxFnPfpA79Ja1RXX/images/session_duration.png?fit=max&auto=format&n=oxFnPfpA79Ja1RXX&q=85&s=85951c9bf713a2ded792717e538ba9ce" alt="Diagram comparing synchronous execution (events in sequence) vs asynchronous execution (events in parallel branches)" width="801" height="384" data-path="images/session_duration.png" />
</Frame>

* **Synchronous:** Events chain sequentially (Session Start → Event 1 → Event 2)
* **Asynchronous:** Events branch in parallel from Session Start

If you manually set `duration` on the session, that value is preserved.

## Related

<CardGroup cols={2}>
  <Card title="Alerts" icon="bell" href="/v2/monitoring/alerts/alerts_overview">
    Set up alerts based on session metrics
  </Card>

  <Card title="Charts" icon="chart-line" href="/v2/monitoring/charts">
    Visualize session metrics over time
  </Card>
</CardGroup>