---
title: "Get the factory's run counts grouped by a dimension"
method: GET
path: "/factory/{uid}/metrics/run-breakdown"
tags: ["Factories", "Metrics"]
---

# Get the factory's run counts grouped by a dimension

`GET /factory/{uid}/metrics/run-breakdown`

## Request

- Base URL: `https://app.warp.dev/api/v1`
- URL: `https://app.warp.dev/api/v1/factory/{uid}/metrics/run-breakdown`
- Auth: HTTP bearer

The factory's run counts over a UTC date range, grouped by one
dimension. Pass group_by_period to additionally receive per-period
series aligned to period_list.

## Path parameters

- `uid` string, required

## Query parameters

- `group_by` 'agent_type' | 'status' | 'source' | 'root_vs_subrun' | 'model' | 'harness', required: Grouping dimension for the run-breakdown metric. source counts top-level runs only; every other dimension counts subruns individually.
- `start_date` string, date-time
- `end_date` string, date-time
- `group_by_period` 'day' | 'week' | 'month': Binning granularity for factory metrics series. Weeks start on Sunday (UTC), consistent with existing Warp analytics.

## Response `200`

Grouped run counts for the requested range

- FactoryRunBreakdownResponse: Fields every factory-scoped metrics response carries alongside its data, so responses from several factories can be combined or told apart.
  - `as_of` string, date-time, required: The time the data is current as of. Data can lag live activity by a few minutes.
  - `team_uid` string, required: Public UID of the team that owns the factory.
  - `factory_uid` string, required: Public UID of the factory the response is scoped to.
  - `group_by` 'agent_type' | 'status' | 'source' | 'root_vs_subrun' | 'model' | 'harness', required: Grouping dimension for the run-breakdown metric. source counts top-level runs only; every other dimension counts subruns individually.
  - `group_by_period` 'day' | 'week' | 'month': Binning granularity for factory metrics series. Weeks start on Sunday (UTC), consistent with existing Warp analytics.
  - `period_list` string[]: Period labels every series aligns to (dates like 2026-07-01; weeks labeled by their Sunday start date). Present only when group_by_period was requested.
  - `data` FactoryRunBreakdownData, required: Grouped run counts. Groups are ordered by total descending (key ascending on ties) with the reserved buckets always last — UNKNOWN, then OTHER; group totals and series sum to total and its per-period distribution.
    - `total` integer, required: Sum over groups — top-level runs only when root_runs_only is true, so it can undercount the run_count metric there.
    - `root_run_count` integer, required: The factory's top-level runs (no parent run) in the range, whatever the dimension — the dashboard's companion stat to the all-runs headline. Equals total on root-scoped dimensions.
    - `root_runs_only` boolean: Present and true for the source dimension, which counts top-level runs only.
    - `groups` FactoryRunBreakdownGroup[], required
      - `key` string, required
      - `label` string
      - `total` integer, required
      - `series` integer[]: One entry per period_list entry, zero-filled. Present only when group_by_period was requested.

## Other responses

- `400`: Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested
- `401`: Authentication required
- `404`: Factory not found or not accessible
- `429`: The caller has used up the request budget shared by the factory metrics endpoints. Wait the number of seconds in Retry-After, then retry.
- `500`: Internal server error

## Changes

- **2026-10-21** `7ee3ba55debc`: 2 info
  - api tag `factory-metrics` added
  - api tag `factory` removed
- **2026-10-15** `f4630aae17ba`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/factory/:uid/metrics/run-breakdown/get.md)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) - [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/warp/apis/oz-agent-api/revisions/4b5d145669be?raw)