Platform

Account Usage API

Query balance, request history, usage counters, costs, and saved Playground chats

Use account endpoints when you want to reconcile spend, show usage inside your own product, or export saved Playground tests.

Usage and balance

GET /v1/account/usage returns your current credit balance plus recent usage events for the account attached to the API key.

$curl "https://api.empiriolabs.ai/v1/account/usage?limit=25" \
>  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

You can filter by from, to, before, model, status, and source. Supported source values are api, playground, compose, gpu_cloud, and hosted_agents.

Each usage event includes:

FieldMeaning
sourceapi, playground, compose, gpu_cloud, or hosted_agents
model and endpointWhat was called. For GPU Cloud rows, model is the GPU SKU identifier.
tokensInput, output, cached, and total token counts. Non-token-billed rows, such as GPU Cloud runtime events, return zero token counts and put runtime details in metadata.
cost.amountDebited credits in USD. This is the single source of truth for what was charged on this request.
status, status_code, errorRequest outcome
output_urlsGenerated media URLs when present
metadata.composePresent on Compose parent rows. Includes recipe, mode, phase, total_cost_usd, leg_count, and legs for the model stages that made up the production.
metadata.agent_type / metadata.agent_name / metadata.agent_instance_idPresent on Hosted Agent model calls so you can trace usage back to the agent.
metadata.gpu_slug / metadata.gpu_display / metadata.seconds / metadata.price_hourlyPresent on GPU Cloud runtime events so you can reconcile the display name, runtime, and hourly rate.
metadata.tool_usageMap of {tool_name: count} when a model billed per-tool surcharges (e.g. web_search, image_search, code_interpreter, web_extractor). Only present when at least one tool fired.
metadata.list_cost / metadata.billed_cost / metadata.discount_amountOnly present when an account-level pricing discount was applied. cost.amount already reflects the post-discount amount; these fields document the discount for receipts.

cost.amount is always the final debited amount. The metadata.list_cost / metadata.billed_cost pair is informational. When a discount is applied, cost.amount equals billed_cost. When no discount applies, neither field is set; just read cost.amount.

For GPU Cloud events, use source: "gpu_cloud" plus metadata.seconds and metadata.price_hourly for runtime reporting. The tokens object remains in the response for schema stability, but GPU runtime rows are not token-billed.

For Compose events, use source: "compose" to retrieve full-video production rows:

$curl "https://api.empiriolabs.ai/v1/account/usage?source=compose&limit=20" \
>  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

A Compose row uses endpoint: "/v1/videos/compose" and stores the production breakdown under metadata.compose:

1{
2  "object": "usage_event",
3  "source": "compose",
4  "model": "custom",
5  "endpoint": "/v1/videos/compose",
6  "cost": { "amount": 0.1832, "currency": "USD" },
7  "metadata": {
8    "category": "compose",
9    "compose": {
10      "recipe": "custom",
11      "mode": "render",
12      "phase": "render",
13      "total_cost_usd": 0.1832,
14      "leg_count": 5,
15      "legs": [
16        { "stage": "voice", "model": "inworld-tts-mini", "cost_usd": 0.012 },
17        { "stage": "visual", "model": "seedance-2-0-pro", "cost_usd": 0.14 }
18      ]
19    }
20  }
21}

Read cost.amount for the final debited amount. Use metadata.compose.legs when you want to show which model stages contributed.

Tool usage example

When you call a model that bills per-tool surcharges (Qwen, Perplexity, MiMo, Mistral) and the model invokes those tools, the response includes a normalized tool_usage map:

1{
2  "id": "...",
3  "object": "usage_event",
4  "model": "qwen3-6-plus",
5  "cost": { "amount": 0.084, "currency": "USD" },
6  "tokens": { "input": 1250, "output": 480, "total": 1730 },
7  "metadata": {
8    "tool_usage": {
9      "web_search": 2,
10      "image_search": 1
11    }
12  }
13}

The cost.amount already includes the per-tool surcharges (here: 2 × $0.026 web_search + 1 × $0.0208 image_search + token cost). Use tool_usage to break down which tools contributed.

Saved Playground chats

The public API exposes saved Playground conversations as read-only resources.

List your saved Playground conversations:

$curl "https://api.empiriolabs.ai/v1/playground/conversations" \
>  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Retrieve a single conversation by ID, including its full message history:

$curl "https://api.empiriolabs.ai/v1/playground/conversations/CONVERSATION_ID" \
>  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Saving and deleting Playground chats still happens in the dashboard.