---
title: "Get run metrics"
method: GET
path: "/runs/metrics"
tags: ["Runs"]
---

# Get run metrics

`GET /runs/metrics`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/runs/metrics`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/runs/metrics/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns your organization's finished runs over a window as points: one per hour or day in time_zone (and per group with group_by), each with the runs by how they ended, the success rate, the median and 95th percentile duration, what they cost and the model steps they took. A run counts in the bucket it finished in; runs still going are not counted. The window defaults to the last 7 days and may start at most a year back; hour buckets need a window of 7 days or less.

## Query parameters

- `period_start_at` string, date-time: Start of the window (RFC 3339). Defaults to 7 days before period_end_at, and may be at most a year before now.
- `period_end_at` string, date-time: End of the window (RFC 3339). Defaults to now, and a later time is read as now.
- `granularity` 'hour' | 'day': Bucket size: hour or day. hour is allowed for windows of 7 days or less.
- `time_zone` string: IANA time zone the buckets follow, such as America/Los_Angeles: a day starts at local midnight and an hour on the local hour. An unknown name is an error.
- `group_by` 'agent' | 'revision' | 'status' | 'trigger' | 'mode' | 'schedule' | 'device_class': Split each bucket by agent, revision, status, trigger, mode, schedule or device_class. Omit for one point per bucket.

## Response `200`

OK

- RunMetricsResponse: Finished runs over the window, one point per bucket (and per group with group_by).
  - `points` RunMetricsPoint[], nullable, required: One point per bucket, oldest first, and per group within a bucket when grouped. The first bucket starts at or before period_start_at.
    - `agent` string: The agent's id. Set only with group_by=agent.
    - `cancelled_runs` integer, required: Of them, the runs that were cancelled.
    - `completed_runs` integer, required: Of them, the runs that completed.
    - `device_class` 'phone': What the runs drove. Set only with group_by=device_class.
    - `duration_p50_ms` integer, nullable, required: Median run duration, start to end, in milliseconds. Null when no run in the bucket has one (a run cancelled before it started).
    - `duration_p95_ms` integer, nullable, required: 95th percentile of the same duration, in milliseconds. Null when no run in the bucket has one.
    - `failed_runs` integer, required: Of them, the runs that failed.
    - `mode` 'agent' | 'code': agent: the model drove; code: a script ran. Set only with group_by=mode.
    - `model_steps` integer, required: Model steps the runs took.
    - `period_start_at` string, date-time, required: Start of the bucket (RFC 3339, UTC): a local hour or a local midnight in time_zone. A run counts in the bucket it finished in.
    - `revision` string: The revision's id; empty for an ad hoc run. Set only with group_by=revision.
    - `runs` integer, required: Runs that finished in the bucket.
    - `schedule` string: The schedule's id; empty for a run no schedule started. Set only with group_by=schedule.
    - `status` 'completed' | 'failed' | 'cancelled': How the runs ended. Set only with group_by=status.
    - `success_rate` number, double, required: Completed runs over finished runs, from 0 to 1; 0 when none finished.
    - `total_cost_microdollars` integer, required: What the runs cost: their sessions' phone time plus the inference made under them, in microdollars. Phone time is billed when a session ends, so a run's cost can land after the run does.
    - `trigger` 'manual' | 'scheduled' | 'api': What started the runs. Set only with group_by=trigger.

## Other responses

- `403`: Forbidden
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-11-02** `62aa324803a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/runs/metrics/get.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)