Platform

Account Usage API

Query balance, request history, token counts, 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. Set source=playground for Playground activity or source=api for direct API requests.

Each usage event includes:

FieldMeaning
sourceapi or playground
model and endpointWhat was called
tokensInput, output, cached, and total token counts
cost.amountDebited credits in USD — single source of truth for what was charged on this request
status, status_code, errorRequest outcome
output_urlsGenerated media URLs when present
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.

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.