Analytics

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. The samples assume the rl client from Client setup.

Before you begin

Any role that can read Managed Agents can read analytics. See 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 verdicts and pass rates.

Read analytics

Console
TypeScript
cURL

In the sidebar, click Analytics.
Choose a view: Usage, Completions, Environments, or Quality.
Choose a time range from Last 24 hours to Last year. The default is Last 7 days.
Read the chart and the Agents, Tools, and Models tables below it. The header shows how current the figures are.

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',
});

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"

{
  "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.
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.

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 for every other limit.

Next steps

Usage and cost

Read one session’s or one tree’s cost.

Evaluations

Score sessions and chart quality over time.

Environments

Fix slow or failing sandbox startups.

Sessions

Open the sessions behind a number.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Before you begin

Metric families

Read analytics

Choose the window and filters

Read the response

Use analytics well

What can go wrong

Limits

Next steps

Usage and cost

Evaluations

Environments

Sessions

​Before you begin

​Metric families

​Read analytics

​Choose the window and filters

​Read the response

​Use analytics well

​What can go wrong

​Limits

​Next steps

Usage and cost

Evaluations

Environments

Sessions

Before you begin

Metric families

Read analytics

Choose the window and filters

Read the response

Use analytics well

What can go wrong

Limits

Next steps