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

# Team Metrics

> Track tokens, cost, requests, tool calls, and timing across every member of a team.

## Overview

Every team exposes a single read-only **`team.usage`** property. It returns an `AggregatedUsage` view derived from the [centralized usage registry](/concepts/usage-registry) on each access, scoped to this team's `team_usage_id`.

Each member's model calls — including sub-pipeline calls like memory summarization, reliability passes, culture, policy, and sub-agents — inherit the team scope and roll into `team.usage` automatically. Nested sub-teams contribute to their parent team's view as well.

## Accessing Team Metrics

Read **`team.usage`** on any `Team` instance. It always returns an `AggregatedUsage` — zero-valued before the first run, populated thereafter.

### Token Metrics

| Property | Type | Description |
| - | - | - |
| `input_tokens` | `int` | Prompt tokens across every team member's model calls |
| `output_tokens` | `int` | Completion tokens across every team member's model calls |
| `total_tokens` | `int` | Sum of `input_tokens + output_tokens` |
| `cache_read_tokens` | `int` | Tokens read from prompt cache |
| `cache_write_tokens` | `int` | Tokens written to prompt cache |
| `reasoning_tokens` | `int` | Reasoning (chain-of-thought) tokens |

### Request & Tool Metrics

| Property | Type | Description |
| - | - | - |
| `requests` | `int` | Total number of LLM API requests across the team |
| `tool_calls` | `int` | Total number of tool calls across the team |

### Timing Metrics

| Property | Type | Description |
| - | - | - |
| `duration` | `float` | Sum of per-call durations recorded on entries (seconds) |
| `model_execution_time` | `float` | Total time spent inside LLM API calls (seconds) |
| `tool_execution_time` | `float` | Total time spent executing tools (seconds) |
| `upsonic_execution_time` | `float` | Framework overhead = `duration − model − tool` (seconds) |
| `time_to_first_token` | `float \| None` | Earliest TTFT across contributing entries |

### Cost Metrics

| Property | Type | Description |
| - | - | - |
| `cost` | `float \| None` | Sum of `cost_usd` across contributing entries. `None` if no entry was priced; `0.0` means priced and free. |

### Aggregation Metadata

| Property | Type | Description |
| - | - | - |
| `entry_count` | `int` | Number of underlying `UsageEntry` rows contributing to this view |
| `models` | `list[str]` | Distinct model identifiers that contributed (first-seen order) |

### Team Identity

| Property | Type | Description |
| - | - | - |
| `team_id` | `str` | Stable identifier for the team |
| `team_usage_id` | `str` | Scope tag used to filter the usage registry for this team |

## Example

```python theme={null}
from upsonic import Agent, Team

team = Team(
    entities=[
        Agent("openai/gpt-4o-mini", name="Researcher"),
        Agent("anthropic/claude-sonnet-4-5", name="Reviewer"),
    ],
)

team.do("Plan and review a small feature.")

u = team.usage
print(f"Requests:        {u.requests}")
print(f"Input tokens:    {u.input_tokens}")
print(f"Output tokens:   {u.output_tokens}")
print(f"Tool calls:      {u.tool_calls}")
if u.cost is not None:
    print(f"Cost:            ${u.cost:.4f}")
print(f"Model time:      {u.model_execution_time:.2f}s")
print(f"Tool time:       {u.tool_execution_time:.2f}s")
print(f"Framework time:  {u.upsonic_execution_time:.2f}s")
print(f"Models used:     {u.models}")
```

## JSON-Friendly Output

```python theme={null}
import json

snapshot = team.usage.to_dict()
print(json.dumps(snapshot, indent=2))
```

## Scope & Propagation

* **Across members** — Every team member's model call records an entry tagged with the team's `team_usage_id`. Reading `team.usage` re-aggregates all of them.
* **Per-member breakdown** — Each agent still has its own `agent_usage_id`. To see one member in isolation, read that agent's `agent.usage`. The same entries contribute to both views (one entry, multiple scope tags).
* **Sub-teams** — When a `Team` is nested inside another `Team`, the nested team's entries carry both `team_usage_id` tags, rolling up into the parent automatically.
* **Sub-pipeline rollup** — Memory summarization, reliability validator/editor, culture, policy, and sub-agent calls dispatched by team members inherit the team scope via context variables.
* **Retry idempotency** — The registry is keyed by `entry_id`. Retried requests replace their prior entry instead of double-counting.
* **JSON snapshot** — Call `team.usage.to_dict()` for a flat dict suitable for logs and dashboards.

## Per-Member Breakdown

```python theme={null}
print("=== Team total ===")
print(team.usage.to_dict())

print("\n=== Per-member ===")
for entity in team.entities:
    print(f"{entity.name}: {entity.usage.to_dict()}")
```

## Legacy Migration

<Note>
  `team.usage` is the unified entry point for all team-level metrics. There is no legacy `team.total_cost` / `team.input_tokens` / `team.get_session_metrics()` surface — `team.usage` was introduced as part of the centralized usage registry rollout.
</Note>

## Related Documentation

* [Usage Registry](/concepts/usage-registry) — Architecture, scope tags, persistence
* [Agent Metrics](/concepts/agents/metrics) — Per-member scoped view
* [Task Metrics](/concepts/tasks/metrics) — Per-task scoped view
* [Chat Metrics](/concepts/chat/metrics) — Per-session scoped view


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