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

# Spend summary

`GET /analytics/summary`

## Request

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

Totals for a range, the comparison period (previous period by default) and the current balance.

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.

## 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
- `include_balance` 'true' | 'false'

## Response `200`

Result envelope

- AnalyticsSummaryResponse
  - `data` AnalyticsSummary, required
    - `spend_cents` integer, required: Credits charged in range.
    - `charges` integer, required
    - `jobs` integer, required
    - `runs` integer, required
    - `unsuccessful_spend_cents` integer, required: Credits charged on jobs that ended failed or cancelled.
    - `unattributed_spend_cents` integer, required: Credits whose job can no longer be identified.
    - `previous` object, nullable, required: Totals for the comparison period, or null.
      - `spend_cents` integer, required: Credits charged in range.
      - `charges` integer, required
      - `jobs` integer, required
      - `runs` integer, required
      - `unsuccessful_spend_cents` integer, required: Credits charged on jobs that ended failed or cancelled.
      - `unattributed_spend_cents` integer, required: Credits whose job can no longer be identified.
      - `from` string, date-time
      - `to` string, date-time
    - `change` object, nullable, required
      - `spend_cents` integer
      - `spend_pct` number, nullable: Percent change; null when the previous period had no spend.
    - `balance` AnalyticsBalance, required: Current balance. Not affected by range or filters.
      - `available_cents` integer, required: Spendable now (total minus held).
      - `total_cents` integer, required
      - `held_cents` integer, required: Held by running jobs.
      - `subscription_cents` integer, required
      - `subscription_expires_at` string, date-time, nullable
      - `rollover_cents` integer, required
      - `rollover_expires_at` string, date-time, nullable
      - `onetime_cents` integer, required
      - `as_of` string, date-time, required
  - `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/summary/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)