Analytics

Spend summary

Changed on

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.

get/analytics/summary

Request

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

Query parameters

fromstring

Range start, inclusive. YYYY-MM-DD (local midnight in timezone), a local date-time (2026-09-01T09:30), or an ISO 8601 instant with offset. Default: to minus 30 days. Ranges are limited to 366 days.

tostring

Range end, exclusive. Same formats as from. Default is now.

timezonestring

IANA timezone used for date-only bounds and calendar buckets. Default UTC.

compare'previous_period' | 'none'

previous_period compares against the equal-length period right before from; none disables comparison. Default is previous_period on /analytics/summary and none elsewhere. Ignored when compare_from/compare_to are given.

compare_fromstring

Explicit comparison start. Must be sent together with compare_to.

compare_tostring

Explicit comparison end, exclusive. Must be sent together with compare_from.

toolstring

Filter by capability. Comma-separated tool keys (video, image, speech, music, render, pipeline, ...) or none. Up to 50 values.

modelstring

Filter by model. Comma-separated model ids or none. Up to 50 values.

workspace_idstring

Filter by folder. Comma-separated folder ids or none (no folder). Up to 50 values.

api_key_idstring

Filter by the API key that started the run. Comma-separated key ids or none. Up to 50 values.

member_idstring

Filter by the person who started the run. Comma-separated user ids or none. Up to 50 values.

creatorstring

Filter by creator: api_key:<id> (a personal API key) or member:<id> (a person), comma-separated, or none. Up to 50 values.

sourcestring

Filter by how the run was started. Comma-separated values of app (a person in the web app), api (API key, SDK, CLI), mcp (an agent via MCP), internal (varg system keys), unknown.

statusstring

Filter by the charged job's status. Comma-separated values of completed, failed, cancelled, awaiting_confirmation, running, submitting, queued, unknown.

include_balance'true' | 'false'

Include the current balance in the response. Default true.

Response

Result envelope

Example response

{
  "data": {
    "spend_cents": 4210,
    "charges": 96,
    "jobs": 80,
    "runs": 61,
    "unsuccessful_spend_cents": 120,
    "unattributed_spend_cents": 0,
    "previous": null,
    "change": null,
    "balance": null
  },
  "meta": {
    "definition_version": "2026-09-28",
    "from": "2026-09-20T00:00:00.000Z",
    "to": "2026-10-20T00:00:00.000Z",
    "timezone": "UTC",
    "compare": null,
    "filters": {},
    "data_as_of": "2026-10-20T10:00:00.000Z",
    "money_unit": "cent",
    "time_basis": "posted_at",
    "attribution_scope": "full"
  }
}

Changes