Read pre-aggregated session, usage, and environment analytics

curl --request GET \
  --url https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "as_of": "2026-02-18T09:30:00.000Z",
  "breakdowns": [
    {
      "dimension": "example",
      "rows": [
        {
          "cache_read_tokens": 1,
          "cache_write_tokens": 1,
          "criterion_count": 1,
          "criterion_fail_count": 1,
          "criterion_not_applicable_count": 1,
          "criterion_pass_count": 1,
          "criterion_pass_rate": 1.5,
          "duration_samples": 1,
          "environment_failed": 1,
          "environment_ready": 1,
          "environment_starts": 1,
          "environment_startup_ms": 1,
          "evaluation_count": 1,
          "evaluation_fail_count": 1,
          "evaluation_not_applicable_count": 1,
          "evaluation_pass_count": 1,
          "evaluation_pass_rate": 1.5,
          "event_count": 1,
          "input_tokens": 1,
          "label": "example",
          "model_calls": 1,
          "model_cost_micros": 1,
          "output_tokens": 1,
          "p50_ms": 1.5,
          "p90_ms": 1.5,
          "p95_ms": 1.5,
          "session_completion_ms": 1,
          "sessions": 1,
          "tool_calls": 1,
          "tool_completed": 1,
          "tool_cost_micros": 1,
          "tool_duration_ms": 1,
          "tool_failed": 1,
          "tool_in_flight": 1,
          "total_cost_micros": 1,
          "turns": 1,
          "value": "example"
        }
      ]
    }
  ],
  "family": "example",
  "family_version": 1,
  "from": "2026-02-18T09:30:00.000Z",
  "granularity": "hour",
  "lag_seconds": 1,
  "scope": "workspace",
  "series": [
    {
      "bucket_start": "2026-02-18T09:30:00.000Z",
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "criterion_count": 1,
      "criterion_fail_count": 1,
      "criterion_not_applicable_count": 1,
      "criterion_pass_count": 1,
      "criterion_pass_rate": 1.5,
      "duration_samples": 1,
      "environment_failed": 1,
      "environment_ready": 1,
      "environment_starts": 1,
      "environment_startup_ms": 1,
      "evaluation_count": 1,
      "evaluation_fail_count": 1,
      "evaluation_not_applicable_count": 1,
      "evaluation_pass_count": 1,
      "evaluation_pass_rate": 1.5,
      "event_count": 1,
      "input_tokens": 1,
      "model_calls": 1,
      "model_cost_micros": 1,
      "output_tokens": 1,
      "p50_ms": 1.5,
      "p90_ms": 1.5,
      "p95_ms": 1.5,
      "session_completion_ms": 1,
      "sessions": 1,
      "tool_calls": 1,
      "tool_completed": 1,
      "tool_cost_micros": 1,
      "tool_duration_ms": 1,
      "tool_failed": 1,
      "tool_in_flight": 1,
      "total_cost_micros": 1,
      "turns": 1
    }
  ],
  "series_group_by": "example",
  "series_groups": [
    {
      "label": "example",
      "points": [
        {
          "bucket_start": "2026-02-18T09:30:00.000Z",
          "cache_read_tokens": 1,
          "cache_write_tokens": 1,
          "criterion_count": 1,
          "criterion_fail_count": 1,
          "criterion_not_applicable_count": 1,
          "criterion_pass_count": 1,
          "criterion_pass_rate": 1.5,
          "duration_samples": 1,
          "environment_failed": 1,
          "environment_ready": 1,
          "environment_starts": 1,
          "environment_startup_ms": 1,
          "evaluation_count": 1,
          "evaluation_fail_count": 1,
          "evaluation_not_applicable_count": 1,
          "evaluation_pass_count": 1,
          "evaluation_pass_rate": 1.5,
          "event_count": 1,
          "input_tokens": 1,
          "model_calls": 1,
          "model_cost_micros": 1,
          "output_tokens": 1,
          "p50_ms": 1.5,
          "p90_ms": 1.5,
          "p95_ms": 1.5,
          "session_completion_ms": 1,
          "sessions": 1,
          "tool_calls": 1,
          "tool_completed": 1,
          "tool_cost_micros": 1,
          "tool_duration_ms": 1,
          "tool_failed": 1,
          "tool_in_flight": 1,
          "total_cost_micros": 1,
          "turns": 1
        }
      ],
      "value": "example"
    }
  ],
  "to": "2026-02-18T09:30:00.000Z",
  "totals": {
    "cache_read_tokens": 1,
    "cache_write_tokens": 1,
    "criterion_count": 1,
    "criterion_fail_count": 1,
    "criterion_not_applicable_count": 1,
    "criterion_pass_count": 1,
    "criterion_pass_rate": 1.5,
    "duration_samples": 1,
    "environment_failed": 1,
    "environment_ready": 1,
    "environment_starts": 1,
    "environment_startup_ms": 1,
    "evaluation_count": 1,
    "evaluation_fail_count": 1,
    "evaluation_not_applicable_count": 1,
    "evaluation_pass_count": 1,
    "evaluation_pass_rate": 1.5,
    "event_count": 1,
    "input_tokens": 1,
    "model_calls": 1,
    "model_cost_micros": 1,
    "output_tokens": 1,
    "p50_ms": 1.5,
    "p90_ms": 1.5,
    "p95_ms": 1.5,
    "session_completion_ms": 1,
    "sessions": 1,
    "tool_calls": 1,
    "tool_completed": 1,
    "tool_cost_micros": 1,
    "tool_duration_ms": 1,
    "tool_failed": 1,
    "tool_in_flight": 1,
    "total_cost_micros": 1,
    "turns": 1
  }
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

Analytics

Read pre-aggregated session, usage, and environment analytics

Returns totals, a time series, and default breakdowns for one metric family over a time window. Figures are kept up to date as work happens rather than recomputed from session events, so the cost of a request depends on the window rather than on how much history the organization has, and every response reports its own freshness through as_of and lag_seconds. Percentiles are approximate. scope defaults to the caller’s own organization, which is the scope an organization member reads; tenant and global need a tenant-administrator identity and answer 403 otherwise.

GET

managed-agents

analytics

{family}

Read pre-aggregated session, usage, and environment analytics

curl --request GET \
  --url https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/analytics/{family}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "as_of": "2026-02-18T09:30:00.000Z",
  "breakdowns": [
    {
      "dimension": "example",
      "rows": [
        {
          "cache_read_tokens": 1,
          "cache_write_tokens": 1,
          "criterion_count": 1,
          "criterion_fail_count": 1,
          "criterion_not_applicable_count": 1,
          "criterion_pass_count": 1,
          "criterion_pass_rate": 1.5,
          "duration_samples": 1,
          "environment_failed": 1,
          "environment_ready": 1,
          "environment_starts": 1,
          "environment_startup_ms": 1,
          "evaluation_count": 1,
          "evaluation_fail_count": 1,
          "evaluation_not_applicable_count": 1,
          "evaluation_pass_count": 1,
          "evaluation_pass_rate": 1.5,
          "event_count": 1,
          "input_tokens": 1,
          "label": "example",
          "model_calls": 1,
          "model_cost_micros": 1,
          "output_tokens": 1,
          "p50_ms": 1.5,
          "p90_ms": 1.5,
          "p95_ms": 1.5,
          "session_completion_ms": 1,
          "sessions": 1,
          "tool_calls": 1,
          "tool_completed": 1,
          "tool_cost_micros": 1,
          "tool_duration_ms": 1,
          "tool_failed": 1,
          "tool_in_flight": 1,
          "total_cost_micros": 1,
          "turns": 1,
          "value": "example"
        }
      ]
    }
  ],
  "family": "example",
  "family_version": 1,
  "from": "2026-02-18T09:30:00.000Z",
  "granularity": "hour",
  "lag_seconds": 1,
  "scope": "workspace",
  "series": [
    {
      "bucket_start": "2026-02-18T09:30:00.000Z",
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "criterion_count": 1,
      "criterion_fail_count": 1,
      "criterion_not_applicable_count": 1,
      "criterion_pass_count": 1,
      "criterion_pass_rate": 1.5,
      "duration_samples": 1,
      "environment_failed": 1,
      "environment_ready": 1,
      "environment_starts": 1,
      "environment_startup_ms": 1,
      "evaluation_count": 1,
      "evaluation_fail_count": 1,
      "evaluation_not_applicable_count": 1,
      "evaluation_pass_count": 1,
      "evaluation_pass_rate": 1.5,
      "event_count": 1,
      "input_tokens": 1,
      "model_calls": 1,
      "model_cost_micros": 1,
      "output_tokens": 1,
      "p50_ms": 1.5,
      "p90_ms": 1.5,
      "p95_ms": 1.5,
      "session_completion_ms": 1,
      "sessions": 1,
      "tool_calls": 1,
      "tool_completed": 1,
      "tool_cost_micros": 1,
      "tool_duration_ms": 1,
      "tool_failed": 1,
      "tool_in_flight": 1,
      "total_cost_micros": 1,
      "turns": 1
    }
  ],
  "series_group_by": "example",
  "series_groups": [
    {
      "label": "example",
      "points": [
        {
          "bucket_start": "2026-02-18T09:30:00.000Z",
          "cache_read_tokens": 1,
          "cache_write_tokens": 1,
          "criterion_count": 1,
          "criterion_fail_count": 1,
          "criterion_not_applicable_count": 1,
          "criterion_pass_count": 1,
          "criterion_pass_rate": 1.5,
          "duration_samples": 1,
          "environment_failed": 1,
          "environment_ready": 1,
          "environment_starts": 1,
          "environment_startup_ms": 1,
          "evaluation_count": 1,
          "evaluation_fail_count": 1,
          "evaluation_not_applicable_count": 1,
          "evaluation_pass_count": 1,
          "evaluation_pass_rate": 1.5,
          "event_count": 1,
          "input_tokens": 1,
          "model_calls": 1,
          "model_cost_micros": 1,
          "output_tokens": 1,
          "p50_ms": 1.5,
          "p90_ms": 1.5,
          "p95_ms": 1.5,
          "session_completion_ms": 1,
          "sessions": 1,
          "tool_calls": 1,
          "tool_completed": 1,
          "tool_cost_micros": 1,
          "tool_duration_ms": 1,
          "tool_failed": 1,
          "tool_in_flight": 1,
          "total_cost_micros": 1,
          "turns": 1
        }
      ],
      "value": "example"
    }
  ],
  "to": "2026-02-18T09:30:00.000Z",
  "totals": {
    "cache_read_tokens": 1,
    "cache_write_tokens": 1,
    "criterion_count": 1,
    "criterion_fail_count": 1,
    "criterion_not_applicable_count": 1,
    "criterion_pass_count": 1,
    "criterion_pass_rate": 1.5,
    "duration_samples": 1,
    "environment_failed": 1,
    "environment_ready": 1,
    "environment_starts": 1,
    "environment_startup_ms": 1,
    "evaluation_count": 1,
    "evaluation_fail_count": 1,
    "evaluation_not_applicable_count": 1,
    "evaluation_pass_count": 1,
    "evaluation_pass_rate": 1.5,
    "event_count": 1,
    "input_tokens": 1,
    "model_calls": 1,
    "model_cost_micros": 1,
    "output_tokens": 1,
    "p50_ms": 1.5,
    "p90_ms": 1.5,
    "p95_ms": 1.5,
    "session_completion_ms": 1,
    "sessions": 1,
    "tool_calls": 1,
    "tool_completed": 1,
    "tool_cost_micros": 1,
    "tool_duration_ms": 1,
    "tool_failed": 1,
    "tool_in_flight": 1,
    "total_cost_micros": 1,
    "turns": 1
  }
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

A Recursion API key, created in the console under API keys.

Path Parameters

family

enum<string>

required

Metric family to read: managed_agent_usage for tool, token, and cost figures, managed_agent_turn for turn counts and turn duration percentiles, managed_agent_environment for sandbox startup latency, managed_agent_completion for first successful root-session completions, and managed_agent_quality for immutable evaluation and criterion verdicts.

Available options:

managed_agent_usage,

managed_agent_turn,

managed_agent_environment,

managed_agent_completion,

managed_agent_quality

Query Parameters

scope

enum<string>

default:workspace

Read locality. workspace is the caller's own organization; tenant aggregates every workspace in the parent tenant organization and requires a Tenant Admin role.

Available options:

workspace,

tenant

workspace_id

string

With scope=tenant, narrow to one workspace of the tenant. Ignored at workspace scope, where the authenticated organization is authoritative.

from

string

RFC 3339 start of the window. Defaults to seven days before to. Widened outward to a bucket boundary.

string

RFC 3339 exclusive end of the window. Defaults to now.

granularity

enum<string>

Series bucket width. Defaults to hourly for windows up to two days and daily beyond that.

Available options:

hour,

day

launched_agent_id

string

Filter to work under sessions launched from this agent, including its subagents.

executing_agent_id

string

Filter to work performed by this agent, whether it was launched directly or delegated to.

executing_agent_version_id

string

Filter to one immutable agent version.

model

string

Filter to one provider model id.

tool_name

string

Filter to one tool. Note that token and cost figures are model spend and are not attributable to a tool, so filtering by one reports only that tool's own direct cost.

outcome

enum<string>

Filter by outcome: tool call state for usage, startup result for environments, or immutable verdict for quality.

Available options:

in_flight,

completed,

failed,

ready,

pending,

pass,

fail,

not_applicable

sandbox_provider

string

Filter environment analytics to one sandbox provider, e.g. runs or docker. self_hosted is accepted for historical queries.

environment_id

string

Filter environment analytics to one environment.

compute_class

string

Filter environment analytics by compute kind: cpu, or an accelerator type and name such as gpu:a100.

machine_type

string

Filter environment analytics to one machine type, or to the requested CPU and memory shape when the provider names none.

target_agent_id

string

Filter quality analytics to evaluations of one target agent.

target_agent_version_id

string

Filter quality analytics to one immutable target-agent version.

evaluator_agent_id

string

Filter quality analytics to verdicts produced by one evaluator agent.

evaluator_agent_version_id

string

Filter quality analytics to one immutable evaluator-agent version.

criterion_key

string

Filter quality analytics to one stable rubric criterion key.

archetype

string

Filter quality analytics by the target task archetype frozen on the evaluation.

size_bucket

string

Filter quality analytics by the target size bucket frozen on the evaluation.

series_group_by

string

Return the series split into one line per value of this dimension, for a stacked chart, alongside the combined series. Capped at the top eight groups by the family's ranking measure. Omit for the combined series only.

limit

integer

default:25

Rows per breakdown.

Required range: x <= 100

Response

Pre-aggregated analytics for one metric family, scope, and time window. Figures are kept up to date as work happens rather than recomputed from session events, so a response is fast regardless of how much history the organization has, and states its own freshness through as_of and lag_seconds.

as_of

string<date-time>

required

How current these figures are. Activity after this instant is counted in a later read.

breakdowns

object[] | null

required

The family's default groupings, each capped by limit.

Show child attributes

family

string

required

Metric family these figures come from.

family_version

integer<int64>

required

Version of the family's definition. A change here means how the figures are derived changed.

from

string<date-time>

required

Inclusive start actually aggregated, widened outward to a bucket boundary.

granularity

enum<string>

required

Width of each series bucket. Chosen from the window: hourly up to two days, daily beyond that.

Available options:

hour,

day

lag_seconds

integer<int64>

required

Seconds between as_of and now. A steady value under a minute is normal; a growing one means the figures are catching up.

scope

enum<string>

required

Read locality the figures were aggregated at, after authorization. This may be narrower than the scope requested.

Available options:

workspace,

tenant,

global

series

object[] | null

required

One point per time bucket, ascending. Buckets with no activity are omitted rather than zero-filled.

Show child attributes

string<date-time>

required

Exclusive end actually aggregated, widened outward to a bucket boundary.

totals

object

required

The whole window aggregated into one figure set.

Show child attributes

Example:

{
  "cache_read_tokens": 1,
  "cache_write_tokens": 1,
  "criterion_count": 1,
  "criterion_fail_count": 1,
  "criterion_not_applicable_count": 1,
  "criterion_pass_count": 1,
  "criterion_pass_rate": 1.5,
  "duration_samples": 1,
  "environment_failed": 1,
  "environment_ready": 1,
  "environment_starts": 1,
  "environment_startup_ms": 1,
  "evaluation_count": 1,
  "evaluation_fail_count": 1,
  "evaluation_not_applicable_count": 1,
  "evaluation_pass_count": 1,
  "evaluation_pass_rate": 1.5,
  "event_count": 1,
  "input_tokens": 1,
  "model_calls": 1,
  "model_cost_micros": 1,
  "output_tokens": 1,
  "p50_ms": 1.5,
  "p90_ms": 1.5,
  "p95_ms": 1.5,
  "session_completion_ms": 1,
  "sessions": 1,
  "tool_calls": 1,
  "tool_completed": 1,
  "tool_cost_micros": 1,
  "tool_duration_ms": 1,
  "tool_failed": 1,
  "tool_in_flight": 1,
  "total_cost_micros": 1,
  "turns": 1
}

series_group_by

string

Dimension series_groups is split by, echoing the request. Absent when no stacked series was asked for.

series_groups

object[]

One band per dimension value, for a stacked chart. Present only when series_group_by was requested.

Show child attributes

API reference

Endpoints

Read pre-aggregated session, usage, and environment analytics

Authorizations

Path Parameters

Query Parameters

Response