Usage
Two ledgers sit behind every invoice: one row per data call, and one row per model event. You can read both back over REST, from inside an agent session, or in the dashboard. Nothing is sampled and nothing is rolled up before you see it.
What is recorded where
Data calls and AI events land in different ledgers because they carry different dimensions. A data call has a provider and a status; a model event has a model, a category and the agent and session it belongs to.
| Ledger | One row per | Carries |
|---|---|---|
| data usage | every curated data-source call and every connection call | provider, cost in cents, status, latency, the API key that made the call, and the workspace it belongs to |
| AI usage | every metered model event or runtime tick | model, category, credits charged, and the deployed agent and session it is attributed to |
- Successful data calls are recorded at their real charged cost, after the organization discount.
- Failed data calls are recorded at zero. The row exists so you can see the failure; it costs nothing.
- Connection calls are always recorded at zero, because you are paying the vendor with your own credentials.
- The /v1/db/* routes write no usage rows at all. The workspace database is not metered per query.
AI categories are input, output, cache_read, cache_creation_5m, cache_creation_1h, tool_use and env_active_seconds.
Reading usage over REST
GET /v1/usage returns the data ledger for the key's workspace, newest first.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | optional | Rows to return. Defaults to 50. |
offset | query | integer | optional | Rows to skip. Defaults to 0. |
providerId | query | string | optional | Filter to one provider, by its public slug (for example x, reddit, youtube). |
status | query | success | error | cached | optional | Filter by call outcome. |
from | query | string (ISO 8601) | optional | Lower bound on the row timestamp. Inclusive. |
to | query | string (ISO 8601) | optional | Upper bound on the row timestamp. Inclusive. |
this surface pages by offset
limit and offset. Cursors are used only by the two webhook delivery lists, and the curated data sources page with each upstream's own continuation operations, so do not carry one convention across the three.curl "https://api.superagnt.com/v1/usage?limit=50&offset=0&status=success" \
-H "Authorization: Bearer $AGNTDATA_API_KEY"Reading usage from an agent
Four tools cover the ledger from inside a session, from raw rows up to a windowed summary.
| Tool | Returns |
|---|---|
agnt_usage_recent | The most recent data-usage rows for this workspace, across data-source and connection calls. Filterable by provider. |
agnt_usage_ai_recent | The per-event AI ledger: one row per model event or runtime tick, with model, category, credits charged, deployed agent and session. Filterable by any of those, plus a window. |
agnt_usage_sessions | Top agent sessions in a window, ranked by AI spend or by event count. Answers which sessions blew up last week. |
agnt_usage_summary | The windowed breakdown: totals, AI spend by category and by model, data spend by provider, a per-agent split, a daily series, and an optional cross-tab. |
The summary takes either an explicit from and to or a lookback_days convenience window. Pass group_by with one or two dimensions to get a cross-tab: day and model answers which model drove Tuesday's spike, agent and provider answers which agent leans hardest on each data source. AI-only dimensions cannot be combined with data-only ones.
use the dollar mirror, not the cents field
*_cents field is paired with a *_usd field that is already divided by 100. Display surfaces must read the dollar field. Dividing the cents field by hand is how a total of $262.97 gets rendered as two and a half cents.One honest caveat on agnt_usage_sessions: data spend is not attributed per session today, so the data-call count on a session row is a time-window proxy for how much data work happened during it, not an exact cost.
In the dashboard
The workspace usage page plots the same two ledgers over the last 7, 30 or 90 days. Data credits are split by where the money came from, subscription allowance against purchased balance. AI credits are split by what consumed them: input, output, cache, runtime and tool use. Under both sits the raw call table. The per-agent breakdown is one click away, behind Investigate agents — usually the fastest way to find the agent that got expensive.
Attribution
Usage rows are workspace-scoped while credits are organization-scoped. That asymmetry is deliberate: it lets several workspaces draw on one balance while still answering which of them spent it. Every data row also carries the API key that made the call, so a runaway integration can be traced to a credential and that credential revoked without touching anything else.
Reading usage requires membership in the workspace the rows belong to. Spending, by contrast, is restricted to organization owners and admins, as covered in Credits and wallets.