Account Usage API

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, a usage summary for the query window, an account-level spend breakdown by product, and 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"

Query parameters

Response shape

1
{
2
  "object": "account_usage",
3
  "balance": {
4
    "amount": 42.5,
5
    "currency": "USD",
6
    "auto_topup_enabled": true,
7
    "auto_topup_threshold": 10,
8
    "auto_topup_amount": 50,
9
    "updated_at": "2026-07-10T18:04:11Z"
10
  },
11
  "plan": {
12
    "slug": "pro",
13
    "display_name": "Pro",
14
    "status": "active",
15
    "billing_cadence": "monthly",
16
    "current_period_end": "2026-09-08T18:04:11Z",
17
    "cancel_at_period_end": false,
18
    "window": {
19
      "start": "2026-08-08T18:04:11Z",
20
      "end": "2026-08-15T18:04:11Z"
21
    }
22
  },
23
  "summary": {
24
    "requests": 25,
25
    "total_cost": 0.8412,
26
    "total_tokens": 154200,
27
    "input_tokens": 120400,
28
    "output_tokens": 33800,
29
    "cache_read_tokens": 41200,
30
    "cache_write_tokens": 0,
31
    "cache_hit_rate": 0.3422,
32
    "errors": 1,
33
    "avg_latency_ms": 2140
34
  },
35
  "spend": {
36
    "currency": "USD",
37
    "total": 18.4029,
38
    "model": 12.1103,
39
    "compose": 1.2926,
40
    "gpu_cloud": 4.2,
41
    "hosted_agents": 0.8,
42
    "from": null,
43
    "to": null
44
  },
45
  "data": [ ... ],
46
  "has_more": true,
47
  "next_cursor": "2026-07-08T19:22:41.512Z"
48
}

summary.cache_hit_rate is the share of input tokens served from prompt cache across the query window (cache_read / input, 0 to 1, null when the window has no input tokens). Cached input bills at the model’s cache-read rate, so this is your effective input-cost discount signal. Filter by model to get a per-model rolling rate.

Usage events

Each usage event includes:

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 subscription usage, cost.included and cost.partial are mutually exclusive. A partly covered request starts only when the available credit balance can cover its full pay-as-you-go remainder. If not, it returns 402 insufficient_credits and creates no usage charge or plan draw.

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
  "tool_breakdown": [
8
    { "name": "web_search", "count": 2, "unit_cost_usd": 0.026, "subtotal_usd": 0.052 },
9
    { "name": "image_search", "count": 1, "unit_cost_usd": 0.0208, "subtotal_usd": 0.0208 }
10
  ],
11
  "metadata": {
12
    "tool_usage": {
13
      "web_search": 2,
14
      "image_search": 1
15
    }
16
  }
17
}

The cost.amount already includes the per-tool surcharges (here: 2 × $0.026 web_search + 1 × $0.0208 image_search + token cost). metadata.tool_usage is the raw invocation-count map; tool_breakdown adds the per-tool unit cost and subtotal so you can render a billing breakdown without fetching catalog pricing yourself.

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 Playground.