> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Analytics
> Chart tool calls, tokens, cost, turns, session completion, sandbox startup, and evaluation quality across your organization's sessions, with breakdowns by agent, tool, and model.
Analytics adds up activity across every session in your organization: what agents did, what it cost, how long sessions took to finish, and how fast sandboxes started. Use it to spot a failing tool, a costly model, or a slow environment, then open the sessions behind the number. For one session or one tree, see [Usage and cost](/managed-agents/usage-and-cost).
The samples assume the `rl` client from [Client setup](/managed-agents/api#client-setup).
## Before you begin
* Any role that can read Managed Agents can read analytics. See [Organizations and roles](/managed-agents/organizations-and-roles).
* Figures cover your own organization.
## Metric families
Each request reads one **family**.
| Family | Console view | What it measures |
| --------------------------- | ---------------- | ------------------------------------------------------------------ |
| `managed_agent_usage` | **Usage** | Tool calls and their results, model calls, tokens, and cost. |
| `managed_agent_completion` | **Completions** | Root sessions that finished successfully, and how long they took. |
| `managed_agent_environment` | **Environments** | Sandbox startups, failures, and startup time. |
| `managed_agent_turn` | | Model turns and turn duration. |
| `managed_agent_quality` | **Quality** | [Evaluation](/managed-agents/evaluations) verdicts and pass rates. |
## Read analytics
1. In the sidebar, click **Analytics**.
2. Choose a view: **Usage**, **Completions**, **Environments**, or **Quality**.
3. Choose a time range from **Last 24 hours** to **Last year**. The default is **Last 7 days**.
4. Read the chart and the **Agents**, **Tools**, and **Models** tables below it. The header shows how current the figures are.
```typescript theme={"theme":"css-variables"}
const usage = await rl.managedAgents.getAnalytics({
family: 'managed_agent_usage',
from: '2026-09-18T00:00:00Z',
to: '2026-09-25T00:00:00Z',
executing_agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
});
```
```bash theme={"theme":"css-variables"}
curl 'https://api.recursion.labelbox.com/managed-agents/v1/analytics/managed_agent_usage?from=2026-09-18T00:00:00Z&to=2026-09-25T00:00:00Z&executing_agent_id=5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55' \
-H "Authorization: Bearer $RECURSION_API_KEY"
```
```json theme={"theme":"css-variables"}
{
"family": "managed_agent_usage",
"family_version": 1,
"scope": "workspace",
"granularity": "day",
"from": "2026-09-18T00:00:00Z",
"to": "2026-09-25T00:00:00Z",
"as_of": "2026-09-25T11:31:02Z",
"lag_seconds": 18,
"totals": {
"sessions": 42,
"event_count": 3180,
"tool_calls": 2210,
"tool_completed": 2135,
"tool_failed": 71,
"tool_in_flight": 4,
"model_calls": 925,
"input_tokens": 18450210,
"output_tokens": 612904,
"cache_read_tokens": 12930114,
"cache_write_tokens": 1402277,
"model_cost_micros": 48210300,
"tool_cost_micros": 120000,
"total_cost_micros": 48330300,
"duration_samples": 2206,
"p50_ms": 840,
"p95_ms": 12400
},
"series": [
{ "bucket_start": "2026-09-18T00:00:00Z", "sessions": 6, "tool_calls": 301, "total_cost_micros": 6120400 }
],
"breakdowns": [
{
"dimension": "tool_name",
"rows": [
{ "value": "bash", "tool_calls": 1204, "tool_failed": 38, "total_cost_micros": 0 }
]
}
]
}
```
Money is in micro-USD: `1000000` is one US dollar. Every figure set has the same fields; a family fills the ones it measures and reports zero for the rest.
## Choose the window and filters
| Query | Meaning |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `from`, `to` | RFC 3339 times. `from` defaults to seven days before `to`, and `to` defaults to now. Both are widened outward to a whole bucket. |
| `granularity` | `hour` or `day`. By default, hourly for windows up to two days and daily beyond that. |
| `launched_agent_id` | Work under sessions started from this agent, including its subagents. |
| `executing_agent_id` | Work this agent did, whether it was started directly or delegated to. |
| `executing_agent_version_id` | One agent version. |
| `model` | One model id. |
| `tool_name` | One tool. Token and cost figures are model spend, so filtering by a tool reports only that tool's own direct cost. |
| `outcome` | Tool call state for usage (`in_flight`, `completed`, `failed`), startup result for environments (`ready`, `failed`, `pending`), or verdict for quality (`pass`, `fail`, `not_applicable`). |
| `environment_id`, `compute_class`, `machine_type`, `sandbox_provider` | Environment filters. `compute_class` is `cpu` or an accelerator such as `gpu:a100`. |
| `target_agent_id`, `evaluator_agent_id`, `criterion_key`, and their version filters | Quality filters. |
| `series_group_by` | Split the series into one line per value of a dimension, such as `tool_name` or `model`, for a stacked chart. The top eight groups are returned in `series_groups`. |
| `limit` | Rows per breakdown, 1 to 100. The default is 25. |
## Read the response
* **`totals`** is the whole window as one figure set. **`series`** is one point per bucket, oldest first; buckets with no activity are left out, so fill them with zero when you chart. **`breakdowns`** are the family's default groupings, each with `rows` ranked by the family's main measure and capped by `limit`.
* **Rows** carry a `value` to pass back as a filter, and a readable `label` for agents, agent versions, and environments.
* **Percentiles** (`p50_ms`, `p90_ms`, `p95_ms`) are approximate. `duration_samples` says how many measurements they come from. Counters and sums are exact. Stacked `series_groups` leave percentiles out.
* **Freshness.** `as_of` is how current the figures are, and `lag_seconds` is how far behind now that is. A steady lag under a minute is normal; activity after `as_of` shows up in a later read.
**What each family counts.** `sessions` counts sessions once, in the bucket they started in. In `managed_agent_completion`, it counts root sessions by when they first finished successfully, and `session_completion_ms` divided by `sessions` is the mean time to finish. `turns` is filled only by `managed_agent_turn`. `environment_startup_ms` sums startup time over successful startups only.
## Use analytics well
* **Find what's failing.** Read `managed_agent_usage` with `series_group_by=tool_name` and compare `tool_failed` with `tool_calls`.
* **Find where money goes.** Break down by `model` and by `executing_agent_id`, then open that agent's sessions in [Usage and cost](/managed-agents/usage-and-cost).
* **Watch environments.** A rising `environment_failed` or `p95_ms` in `managed_agent_environment` points at a setup script or a machine type.
* **Compare versions.** Filter by `executing_agent_version_id` before and after a change to an agent.
## What can go wrong
| Code or symptom | Cause | Fix |
| ---------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------ |
| `400 invalid_request` | An unknown family, a bad time, `from` after `to`, or a `limit` out of range. | Correct the named field. |
| `400 invalid_scope` | `managed_agent_quality` was asked for a scope other than your organization. | Leave `scope` out. |
| `403 forbidden` | `scope` was set to `tenant`, which needs a tenant-administrator identity. | Leave `scope` out to read your organization. |
| `503 analytics_not_ready` | The figures haven't caught up yet. | Retry shortly. |
| A number looks low for today | `as_of` is a little behind now. | Check `lag_seconds`, and read again in a minute. |
| Gaps in a chart | Buckets with no activity are left out. | Fill missing buckets with zero. |
For every error code, see [Errors](/managed-agents/errors).
## Limits
| Limit | Value |
| --------------------- | -------------------------------------- |
| Rows per breakdown | 1 to 100, default 25 |
| Stacked series groups | 8 |
| Console time ranges | 24 hours, 7, 30, or 90 days, or a year |
See [Limits](/managed-agents/limits) for every other limit.
## Next steps
Read one session's or one tree's cost.
Score sessions and chart quality over time.
Fix slow or failing sandbox startups.
Open the sessions behind a number.