---
title: "Get factory spend grouped by a dimension"
method: GET
path: "/factory/{uid}/costs/breakdown"
tags: ["Factories", "Metrics"]
---

# Get factory spend grouped by a dimension

`GET /factory/{uid}/costs/breakdown`

## Request

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

The factory's spend over a UTC date range, grouped by source, user,
agent, or model. groups lists every entity with nonzero spend in the
range (uncapped); UNKNOWN sorts last. Pass group_by_period to
additionally receive per-period series aligned to period_list.

## Path parameters

- `uid` string, required

## Query parameters

- `group_by` 'source' | 'user' | 'agent' | 'model', required: Grouping dimension for the cost-breakdown metric. source and user roll each run tree's cost to the root run; agent and model keep each run's own cost.
- `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 spend for the requested range

- FactoryCostBreakdownResponse: 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` 'source' | 'user' | 'agent' | 'model', required: Grouping dimension for the cost-breakdown metric. source and user roll each run tree's cost to the root run; agent and model keep each run's own cost.
  - `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` FactoryCostBreakdownData, required: Grouped spend. Groups are ordered by total descending (key ascending on ties) with UNKNOWN always last. The server never caps or folds groups — every entity with nonzero spend is listed.
    - `total` FactoryDollarsBreakdown, required: US dollars the owning team was billed, split by source component: compute (run execution), platform, and inference (recorded per conversation and counted once per distinct conversation). total is the sum of the three. Each charge contributes its recorded billed amount; charges recorded before billed amounts were tracked fall back to an estimated cost.
      - `compute` number, double, required
      - `platform` number, double, required
      - `inference` number, double, required
      - `total` number, double, required
    - `groups` FactoryCostBreakdownGroup[], required
      - `key` string, required
      - `label` string
      - `deleted` boolean, required
      - `photo_url` string: Avatar URL when the group is a user with a resolvable photo.
      - `dollars` FactoryDollarsBreakdown, required: US dollars the owning team was billed, split by source component: compute (run execution), platform, and inference (recorded per conversation and counted once per distinct conversation). total is the sum of the three. Each charge contributes its recorded billed amount; charges recorded before billed amounts were tracked fall back to an estimated cost.
        - `compute` number, double, required
        - `platform` number, double, required
        - `inference` number, double, required
        - `total` number, double, required
      - `series` FactoryDollarsBreakdownSeries: Per-period dollar series aligned to period_list, zero-filled for periods with no attributed cost.
        - `compute` number[], required
        - `platform` number[], required
        - `inference` number[], required
        - `total` number[], required

## 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/costs/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)