> ## Documentation Index > Fetch the complete documentation index at: https://docs.varg.ai/llms.txt > Use this file to discover all available pages before exploring further. # List charges or runs > The ledger charges behind the numbers (`group=charge`), or those charges grouped by run (`group=run`) with each run's lifetime total alongside. Cursor-paginated: pass `next_cursor` as `cursor`. 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`; exports are capped at 10,000 rows and fail with 400 `export_too_large` instead of truncating. ## OpenAPI ````yaml /openapi.yaml get /analytics/activity openapi: 3.1.0 info: title: varg API version: 2.0.0 description: | Unified REST API for AI media generation at `api.varg.ai/v2`. One API key, ~80 models across 8 providers, async jobs, stable output URLs on `s3.varg.ai`, files with lineage, and transparent credit billing (1 credit = 1 cent = $0.01). **The async job pattern:** every generation request returns `202 Accepted` with a job object (`status: queued`). Poll `GET /jobs/{id}` until the job reaches a terminal status (`completed`, `failed`, or `cancelled`), then read `output.outputs[0].url`. Alternatively, set `options.webhook_url` in the request to receive an HMAC-signed callback when the job finishes. servers: - url: https://api.varg.ai/v2 security: - bearerAuth: [] tags: - name: Generation description: >- Create generation jobs (image, video, speech, music, transcription, ffmpeg, render, pipeline) - name: Tools description: Discover tools, their schemas, and call any tool generically - name: Jobs description: Poll and manage job lifecycle - name: Files description: Upload, import, probe, and manage files - name: Folders description: Group files into folders and file generated output automatically - name: Lineage description: Resolve which job produced a file - name: Presets description: Browse and apply reusable parameter values — voices, styles - name: Templates description: Browse, publish, use and render community templates - name: Pricing description: Estimate costs and browse the price catalog - name: Billing description: Balance, usage, and transaction history - name: Analytics description: >- Spend, runs and files over time — summaries, time series, breakdowns, activity - name: Account description: Identity and API key management paths: /analytics/activity: get: tags: - Analytics summary: List charges or runs description: > The ledger charges behind the numbers (`group=charge`), or those charges grouped by run (`group=run`) with each run's lifetime total alongside. Cursor-paginated: pass `next_cursor` as `cursor`. 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`; exports are capped at 10,000 rows and fail with 400 `export_too_large` instead of truncating. operationId: listAnalyticsActivity parameters: - $ref: '#/components/parameters/AnalyticsFrom' - $ref: '#/components/parameters/AnalyticsTo' - $ref: '#/components/parameters/AnalyticsTimezone' - $ref: '#/components/parameters/AnalyticsCompare' - $ref: '#/components/parameters/AnalyticsCompareFrom' - $ref: '#/components/parameters/AnalyticsCompareTo' - $ref: '#/components/parameters/AnalyticsTool' - $ref: '#/components/parameters/AnalyticsModel' - $ref: '#/components/parameters/AnalyticsWorkspaceId' - $ref: '#/components/parameters/AnalyticsApiKeyId' - $ref: '#/components/parameters/AnalyticsMemberId' - $ref: '#/components/parameters/AnalyticsCreator' - $ref: '#/components/parameters/AnalyticsSource' - $ref: '#/components/parameters/AnalyticsStatus' - $ref: '#/components/parameters/AnalyticsActivityGroup' - $ref: '#/components/parameters/AnalyticsActivitySort' - $ref: '#/components/parameters/AnalyticsActivityLimit' - $ref: '#/components/parameters/AnalyticsCursor' - $ref: '#/components/parameters/AnalyticsFormat' responses: '200': description: Result envelope (JSON) or CSV export content: application/json: schema: $ref: '#/components/schemas/AnalyticsActivityResponse' text/csv: schema: type: string description: >- Same rows as the JSON response, flattened. Amounts are in credits. headers: Content-Disposition: description: Attachment filename, `varg-spend-activity--.csv`. schema: type: string '400': description: >- Invalid parameter (code `invalid_request`, `invalid_range`, `range_too_large`, `invalid_timezone`, `invalid_filter`, `unsupported_group_by`, ...) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '503': description: Analytics is temporarily unavailable (`analytics_unavailable`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: AnalyticsFrom: name: from in: query required: false description: > 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. schema: type: string maxLength: 40 example: '2026-09-01' AnalyticsTo: name: to in: query required: false description: Range end, exclusive. Same formats as `from`. Default is now. schema: type: string maxLength: 40 example: '2026-10-01' AnalyticsTimezone: name: timezone in: query required: false description: >- IANA timezone used for date-only bounds and calendar buckets. Default `UTC`. schema: type: string maxLength: 64 example: Europe/Berlin AnalyticsCompare: name: compare in: query required: false description: > `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. schema: type: string enum: - previous_period - none AnalyticsCompareFrom: name: compare_from in: query required: false description: Explicit comparison start. Must be sent together with `compare_to`. schema: type: string maxLength: 40 AnalyticsCompareTo: name: compare_to in: query required: false description: >- Explicit comparison end, exclusive. Must be sent together with `compare_from`. schema: type: string maxLength: 40 AnalyticsTool: name: tool in: query required: false description: >- Filter by capability. Comma-separated tool keys (`video`, `image`, `speech`, `music`, `render`, `pipeline`, ...) or `none`. Up to 50 values. schema: type: string maxLength: 4000 example: video,image AnalyticsModel: name: model in: query required: false description: Filter by model. Comma-separated model ids or `none`. Up to 50 values. schema: type: string maxLength: 4000 AnalyticsWorkspaceId: name: workspace_id in: query required: false description: >- Filter by folder. Comma-separated folder ids or `none` (no folder). Up to 50 values. schema: type: string maxLength: 4000 AnalyticsApiKeyId: name: api_key_id in: query required: false description: >- Filter by the API key that started the run. Comma-separated key ids or `none`. Up to 50 values. schema: type: string maxLength: 4000 AnalyticsMemberId: name: member_id in: query required: false description: >- Filter by the person who started the run. Comma-separated user ids or `none`. Up to 50 values. schema: type: string maxLength: 4000 AnalyticsCreator: name: creator in: query required: false description: > Filter by creator: `api_key:` (a personal API key) or `member:` (a person), comma-separated, or `none`. Up to 50 values. schema: type: string maxLength: 4000 AnalyticsSource: name: source in: query required: false description: > 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`. schema: type: string maxLength: 4000 example: api,mcp AnalyticsStatus: name: status in: query required: false description: > Filter by the charged job's status. Comma-separated values of `completed`, `failed`, `cancelled`, `awaiting_confirmation`, `running`, `submitting`, `queued`, `unknown`. schema: type: string maxLength: 4000 AnalyticsActivityGroup: name: group in: query required: false description: >- `charge` (default) lists individual ledger charges; `run` groups them by run. schema: type: string enum: - charge - run default: charge AnalyticsActivitySort: name: sort in: query required: false description: '`recent` (default) newest first; `amount` largest first.' schema: type: string enum: - recent - amount default: recent AnalyticsActivityLimit: name: limit in: query required: false description: >- Page size. 1-200, default 50. Out-of-range values are clamped. Ignored for CSV. schema: type: integer minimum: 1 maximum: 200 default: 50 AnalyticsCursor: name: cursor in: query required: false description: >- The `next_cursor` of the previous page. Opaque; only valid with the same `group` and `sort`. schema: type: string maxLength: 400 AnalyticsFormat: name: format in: query required: false description: > `json` (default) returns the `{ data, meta }` envelope. `csv` returns the same rows as `text/csv` with a `Content-Disposition` attachment filename. Amounts are in credits. schema: type: string enum: - json - csv schemas: AnalyticsActivityResponse: type: object required: - data - meta properties: data: $ref: '#/components/schemas/AnalyticsActivity' meta: $ref: '#/components/schemas/AnalyticsMeta' ErrorResponse: type: object properties: error: type: object properties: code: type: string example: model_not_found message: type: string example: 'Unknown model: flux-shnell' details: {} AnalyticsActivity: type: object required: - group - items - next_cursor - total properties: group: type: string enum: - charge - run items: type: array description: Charges when `group` is `charge`, runs when `group` is `run`. items: oneOf: - $ref: '#/components/schemas/AnalyticsChargeItem' - $ref: '#/components/schemas/AnalyticsRunItem' next_cursor: type: - string - 'null' description: Pass as `cursor` for the next page; null on the last page. total: type: object description: Totals over the whole range, not just this page. properties: count: type: integer spend_cents: type: integer AnalyticsMeta: type: object description: Metadata describing how the numbers were computed. required: - definition_version - data_as_of - money_unit - time_basis - attribution_scope properties: definition_version: type: string description: Changes whenever a metric's meaning changes. example: '2026-09-28' from: type: string format: date-time description: Resolved range start (inclusive). to: type: string format: date-time description: Resolved range end (exclusive). timezone: type: string example: UTC compare: type: - object - 'null' description: The comparison period, or null when none. properties: from: type: string format: date-time to: type: string format: date-time filters: type: object description: Filters applied, keyed by query parameter name. additionalProperties: type: array items: type: string data_as_of: type: string format: date-time money_unit: type: string enum: - cent description: Amounts are whole credits, in fields ending in `_cents`. time_basis: type: string enum: - posted_at - lifetime - created_at description: >- `posted_at` = when the ledger charge was posted; `created_at` = when a file was made. attribution_scope: type: string enum: - full - self description: '`self` means identity dimensions show only the caller''s own values.' AnalyticsChargeItem: type: object properties: id: type: string description: Ledger charge id. posted_at: type: string format: date-time amount_cents: type: integer billed_units: type: - object - 'null' additionalProperties: true job_id: type: - string - 'null' run_id: type: - string - 'null' tool: $ref: '#/components/schemas/AnalyticsDimensionValue' model: $ref: '#/components/schemas/AnalyticsDimensionValue' status: $ref: '#/components/schemas/AnalyticsDimensionValue' source: $ref: '#/components/schemas/AnalyticsDimensionValue' workspace: $ref: '#/components/schemas/AnalyticsDimensionValue' api_key: $ref: '#/components/schemas/AnalyticsDimensionValue' member: $ref: '#/components/schemas/AnalyticsDimensionValue' AnalyticsRunItem: type: object properties: run_id: type: string spend_in_range_cents: type: integer description: The run's charges that fall in the range and match the filters. run_total_charged_cents: type: integer description: >- Everything the run was ever charged, regardless of range and filters. charges_in_range: type: integer first_posted_at: type: string format: date-time last_posted_at: type: string format: date-time root: type: object description: The run's top-level job. properties: tool: $ref: '#/components/schemas/AnalyticsDimensionValue' model: $ref: '#/components/schemas/AnalyticsDimensionValue' status: $ref: '#/components/schemas/AnalyticsDimensionValue' created_at: type: - string - 'null' format: date-time source: $ref: '#/components/schemas/AnalyticsDimensionValue' member: $ref: '#/components/schemas/AnalyticsDimensionValue' api_key: $ref: '#/components/schemas/AnalyticsDimensionValue' AnalyticsDimensionValue: type: object description: A dimension value with its display label. required: - key - label properties: key: type: string description: Value key, or the special keys `none`, `hidden`, `other`. label: type: string kind: type: string enum: - member - api_key description: Creators only. avatar_url: type: - string - 'null' owner_label: type: - string - 'null' description: Creator keys only; the person the key belongs to. revoked: type: boolean description: API keys only; revoked keys keep their history. deleted: type: boolean description: Folders only; the folder was deleted after the charge. responses: Unauthorized: description: Missing or invalid API key / JWT content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: value: error: code: unauthorized message: Invalid or missing API key or JWT securitySchemes: bearerAuth: type: http scheme: bearer description: | varg API key (`varg_...`). Get one at [app.varg.ai](https://app.varg.ai) or run `bunx vargai login`. App sessions may alternatively send a Supabase JWT. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.