---
title: "Spend over time"
method: GET
path: "/analytics/timeseries"
tags: ["Analytics"]
---

# Spend over time

`GET /analytics/timeseries`

## Request

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

Spend per hour, day, week or month in `timezone`, optionally split by one dimension (top N groups plus `other`).

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` the response is `text/csv`.

## 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
- `bucket_width` '1h' | '1d' | '1w' | '1mo'
- `group_by` 'tool' | 'model' | 'workspace' | 'api_key' | 'member' | 'creator' | 'source' | 'status': A dimension spend can be grouped or filtered by.
- `groups` integer
- `format` 'json' | 'csv'

## Response `200`

Result envelope (JSON) or CSV export

- AnalyticsTimeseriesResponse
  - `data` AnalyticsTimeseries, required
    - `bucket_width` '1h' | '1d' | '1w' | '1mo', required
    - `group_by` 'tool' | 'model' | 'workspace' | 'api_key' | 'member' | 'creator' | 'source' | 'status', required: A dimension spend can be grouped or filtered by.
    - `groups` AnalyticsTimeseriesGroup[], required
      - `key` string, required: Value key, or the special keys `none`, `hidden`, `other`.
      - `label` string, required
      - `kind` 'member' | 'api_key': Creators only.
      - `avatar_url` string, nullable
      - `owner_label` string, nullable: Creator keys only; the person the key belongs to.
      - `revoked` boolean: API keys only; revoked keys keep their history.
      - `deleted` boolean: Folders only; the folder was deleted after the charge.
      - `spend_cents` integer, required
      - `share` number, required: Fraction of total spend, 0-1.
    - `buckets` AnalyticsTimeseriesBucket[], required
      - `start` string, date-time, required
      - `end` string, date-time, required
      - `spend_cents` integer, required
      - `charges` integer, required
      - `is_partial` boolean, required: The bucket is cut by the range edges or still in progress.
      - `groups` object: Spend per group key; present only when `group_by` is set.
    - `total` object, required
      - `spend_cents` integer
      - `charges` 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/timeseries/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)