---
title: "Get Recent Usage"
method: GET
path: "/api/billing/recent-usage"
tags: ["billing"]
---

# Get Recent Usage

`GET /api/billing/recent-usage`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/billing/recent-usage`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

What did the caller spend in the last N minutes? No play_id needed.

Aggregates the same four ledgers as ``/api/billing/cost-by-play`` but
filters by ``created_at >= now() - interval`` instead of by play. Use
when an SDK session ran without a registered play and you still want
"what did I just spend".

- ``minutes`` (default 60, max 1440 = 24h): lookback window.
- ``actor_only`` (default true): include canonical Growth and enrichment
  capability movements carrying the caller's exact actor identity. Source
  and legacy enrichment ledgers lack that attribution and are excluded.
  Pass false for the complete workspace-wide net total across every ledger.

## Query parameters

- `minutes` integer
- `actor_only` boolean

## Response `200`

Successful Response

- RecentUsageResponse: Credit usage for the caller's org over a recent time window. For when you don't have (or didn't register) a play_id and just want "what did I spend in the last N minutes/hours". Scoped to ``auth.org_id`` and, optionally, the caller's ``actor_id`` so users only see their own usage in shared workspaces.
  - `actor_id` string, nullable, required: Actor filter applied to attributable ledgers, or null for workspace-wide usage.
  - `by_capability` RecentUsageCapability[], required: Window credits grouped by capability and accounting owner.
    - `capability_id` string, required: Exact capability identifier.
    - `credits_used` string, required: Exact net credit quantity in canonical decimal notation. Negative values are refunds or corrections recorded during the selected window.
    - `event_count` integer, required: Accounting events included in this row.
    - `owner` 'source_consumed' | 'enrichment_consumed' | 'growth_observed', required: Credit ownership projection: source_consumed is completed source work; enrichment_consumed is completed enrichment work; enrichment_reserved is active unfinished enrichment work; growth_observed is canonical or legacy Growth capability work.
    - `usd_cost` number, required: Projected net USD equivalent at the workspace current overage-credit rate, rounded to six decimal places. Negative values represent refunds or corrections; this is not provider cost or an invoiced amount.
  - `by_owner` RecentUsageOwner[], required: Window credits grouped by accounting owner.
    - `credits_used` string, required: Exact net credit quantity in canonical decimal notation. Negative values are refunds or corrections recorded during the selected window.
    - `event_count` integer, required: Accounting events included in this owner total.
    - `owner` 'source_consumed' | 'enrichment_consumed' | 'growth_observed', required: Credit ownership projection: source_consumed is completed source work; enrichment_consumed is completed enrichment work; enrichment_reserved is active unfinished enrichment work; growth_observed is canonical or legacy Growth capability work.
    - `usd_cost` number, required: Projected net USD equivalent at the workspace current overage-credit rate, rounded to six decimal places. Negative values represent refunds or corrections; this is not provider cost or an invoiced amount.
  - `credits_used` string, required: Exact net credit quantity in canonical decimal notation. Negative values are refunds or corrections recorded during the selected window.
  - `event_count` integer, required: Accounting events in the measured window.
  - `since` string, date-time, required: Inclusive UTC start of the measured window.
  - `until` string, date-time, required: Exclusive UTC end of the measured window.
  - `usd_cost` number, required: Projected net USD equivalent at the workspace current overage-credit rate, rounded to six decimal places. Negative values represent refunds or corrections; this is not provider cost or an invoiced amount.
  - `usd_per_credit` number, required: Current workspace overage-credit price in US dollars used for this projection; zero can mean a configured zero rate or unavailable commercial terms and does not prove that work is free.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)