---
title: "Spend breakdown"
method: GET
path: "/analytics/breakdown"
tags: ["Analytics"]
---

# Spend breakdown

`GET /analytics/breakdown`

## Request

- Base URL: `https://api.varg.ai/v2`
- URL: `https://api.varg.ai/v2/analytics/breakdown`
- Auth: HTTP bearer

Spend ranked by one or two dimensions. Rows plus `other` always add up to `total`. Returns 400 `too_many_groups` when the grouping yields more than 5000 groups.

All analytics endpoints return `{ "data": ..., "meta": ... }`. `meta` carries the resolved range
(`from` inclusive, `to` exclusive, ISO 8601 UTC), `timezone`, the comparison period, applied `filters`,
`data_as_of`, `money_unit`, `time_basis` and `attribution_scope`.

Amounts are whole credits; fields ending in `_cents` are credits (1 credit = 1 cent). Charges are counted
when they were posted to the ledger. On team accounts, non-members only see their own identity
dimensions (`attribution_scope: self`); others collapse into "Other ..." groups.

With `format=csv` every row is exported (no `other` roll-up).

## Query parameters

- `from` string
- `to` string
- `timezone` string
- `compare` 'previous_period' | 'none'
- `compare_from` string
- `compare_to` string
- `tool` string
- `model` string
- `workspace_id` string
- `api_key_id` string
- `member_id` string
- `creator` string
- `source` string
- `status` string
- `group_by` string, required
- `sort` 'spend' | 'charges' | 'jobs' | 'runs'
- `limit` integer
- `format` 'json' | 'csv'

## Response `200`

Result envelope (JSON) or CSV export

- AnalyticsBreakdownResponse
  - `data` AnalyticsBreakdown, required
    - `group_by` AnalyticsDimension[], required
    - `sort` 'spend' | 'charges' | 'jobs' | 'runs', required
    - `rows` AnalyticsBreakdownRow[], required
      - `group` object, required: Group key per requested dimension.
      - `labels` object, required: Display label per requested dimension.
      - `details` object: Extra facts per dimension (avatar, revoked key, deleted folder).
      - `spend_cents` integer, required
      - `share` number, required: Fraction of total spend, 0-1.
      - `charges` integer, required
      - `jobs` integer, required
      - `runs` integer, required
      - `previous_spend_cents` integer: Present only when a comparison period is set.
      - `change_pct` number, nullable
    - `other` object, nullable, required: Groups beyond `limit`, rolled up. Null when nothing was cut.
      - `groups` integer
      - `spend_cents` integer
      - `share` number
      - `charges` integer
      - `jobs` integer
    - `total` object, required
      - `spend_cents` integer
      - `charges` integer
      - `jobs` integer
      - `runs` integer
      - `groups` integer
  - `meta` AnalyticsMeta, required: Metadata describing how the numbers were computed.
    - `definition_version` string, required: Changes whenever a metric's meaning changes.
    - `from` string, date-time: Resolved range start (inclusive).
    - `to` string, date-time: Resolved range end (exclusive).
    - `timezone` string
    - `compare` object, nullable: The comparison period, or null when none.
      - `from` string, date-time
      - `to` string, date-time
    - `filters` object: Filters applied, keyed by query parameter name.
    - `data_as_of` string, date-time, required
    - `money_unit` 'cent', required: Amounts are whole credits, in fields ending in `_cents`.
    - `time_basis` 'posted_at' | 'lifetime' | 'created_at', required: `posted_at` = when the ledger charge was posted; `created_at` = when a file was made.
    - `attribution_scope` 'full' | 'self', required: `self` means identity dimensions show only the caller's own values.

## Other responses

- `400`: Invalid parameter (code `invalid_request`, `invalid_range`, `range_too_large`, `invalid_timezone`, `invalid_filter`, `unsupported_group_by`, ...)
- `401`: Missing or invalid API key / JWT
- `503`: Analytics is temporarily unavailable (`analytics_unavailable`)

## Changes

- **2026-10-20** `43bcf5ea398d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/varg/apis/varg-api/changes/analytics/breakdown/get.md)

---

[API](https://skmtc.dev/varg/apis/varg-api.md) · [All operations](https://skmtc.dev/varg/apis/varg-api/llms.txt) · [OpenAPI document](https://skmtc.dev/varg/apis/varg-api/revisions/09d49a6d852f?raw)