Retrieve account usage | EmpirioLabs AI Docs

{
  "object": "account_usage",
  "balance": {
    "amount": 42.5,
    "currency": "USD",
    "auto_topup_enabled": true,
    "auto_topup_threshold": 10,
    "auto_topup_amount": 50,
    "updated_at": "2026-05-06T00:00:00Z"
  },
  "summary": {
    "requests": 3,
    "total_cost": 0.249386,
    "total_tokens": 5740,
    "input_tokens": 4300,
    "output_tokens": 1440,
    "cache_read_tokens": 0,
    "cache_write_tokens": 0,
    "cache_hit_rate": 0,
    "errors": 0,
    "avg_latency_ms": 1840
  },
  "spend": {
    "currency": "USD",
    "total": 0.249386,
    "model": 0.0124,
    "compose": 0,
    "gpu_cloud": 0.228086,
    "hosted_agents": 0.0089,
    "from": null,
    "to": null
  },
  "data": [
    {
      "id": "19231",
      "object": "usage_event",
      "created_at": "2026-05-06T00:12:03Z",
      "source": "playground",
      "model": "qwen3-7-max",
      "endpoint": "/playground/chat",
      "status": "success",
      "status_code": 200,
      "error": null,
      "request_id": "req_abc123",
      "latency_ms": 1840,
      "tokens": {
        "input": 3100,
        "output": 900,
        "cache_read": 0,
        "cache_write": 0,
        "total": 4000
      },
      "cost": {
        "amount": 0.0124,
        "currency": "USD"
      },
      "tool_breakdown": null,
      "output_urls": [],
      "metadata": {
        "source": "playground"
      }
    },
    {
      "id": "19232",
      "object": "usage_event",
      "created_at": "2026-05-06T00:11:40Z",
      "source": "hosted_agents",
      "model": "qwen3-7-max",
      "endpoint": "/v1/chat/completions",
      "status": "success",
      "status_code": 200,
      "error": null,
      "request_id": "req_def456",
      "latency_ms": 2210,
      "tokens": {
        "input": 1200,
        "output": 540,
        "cache_read": 0,
        "cache_write": 0,
        "total": 1740
      },
      "cost": {
        "amount": 0.0089,
        "currency": "USD"
      },
      "tool_breakdown": null,
      "output_urls": [],
      "metadata": {
        "category": "agents",
        "agent_type": "hermes",
        "agent_name": "My Assistant",
        "agent_instance_id": "8bf95e48-0815-4eee-8dec-141956729c36"
      }
    },
    {
      "id": "19233",
      "object": "usage_event",
      "created_at": "2026-05-06T00:10:12Z",
      "source": "gpu_cloud",
      "model": "gpu-cloud:h100-nvl",
      "endpoint": "/v1/gpu/connect/gpu_inst_123",
      "status": "success",
      "status_code": 200,
      "error": null,
      "request_id": null,
      "latency_ms": null,
      "tokens": {
        "input": 0,
        "output": 0,
        "cache_read": 0,
        "cache_write": 0,
        "total": 0
      },
      "cost": {
        "amount": 0.228086,
        "currency": "USD"
      },
      "tool_breakdown": null,
      "output_urls": [],
      "metadata": {
        "category": "gpu_cloud",
        "gpu_slug": "h100-nvl",
        "gpu_display": "H100 NVL",
        "seconds": 147,
        "price_hourly": 5.6,
        "num_gpus": 1
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Returns the current credit balance, a per-product spend breakdown (model and API usage, Compose, GPU Cloud, and Hosted Agents), plus recent usage events for the account attached to the API key. Each event has a source (api, playground, compose, gpu_cloud, hosted_agents, or template) plus usage counters, request costs, status, model, endpoint, latency, request ID, and generated media URLs. Token-billed rows report token counts. GPU Cloud runtime rows keep the stable tokens object with zero counts and put runtime details such as seconds, price_hourly, and gpu_display in metadata. For an event made by a Hosted Agent, the metadata object also identifies the agent (agent_type, agent_name, agent_instance_id). Models that bill per-tool surcharges surface a per-event tool_breakdown array. The summary object aggregates requests, tokens, cost, errors, latency, and cache_hit_rate across the whole query window (the same from, to, model, status, and source filters as the events), not just the returned page, so its counts are true totals rather than the page size. The spend totals honor the from and to window, or are all-time when neither is set.

Returns the current credit balance, a per-product spend breakdown (model and API usage, Compose, GPU Cloud, and Hosted Agents), plus recent usage events for the account attached to the API key. Each event has a `source` (`api`, `playground`, `compose`, `gpu_cloud`, `hosted_agents`, or `template`) plus usage counters, request costs, status, model, endpoint, latency, request ID, and generated media URLs. Token-billed rows report token counts. GPU Cloud runtime rows keep the stable `tokens` object with zero counts and put runtime details such as `seconds`, `price_hourly`, and `gpu_display` in `metadata`. For an event made by a Hosted Agent, the `metadata` object also identifies the agent (`agent_type`, `agent_name`, `agent_instance_id`). Models that bill per-tool surcharges surface a per-event `tool_breakdown` array. The `summary` object aggregates requests, tokens, cost, errors, latency, and `cache_hit_rate` across the whole query window (the same `from`, `to`, `model`, `status`, and `source` filters as the events), not just the returned page, so its counts are true totals rather than the page size. The `spend` totals honor the `from` and `to` window, or are all-time when neither is set.

Authentication

AuthorizationBearer

Pass your EmpirioLabs API key as a bearer token. The Anthropic-style x-api-key header is also accepted on every endpoint.

Query parameters

limitintegerOptional1-200Defaults to 100

Number of usage events to return.

beforedatetimeOptional

Return events created before this timestamp. Use next_cursor for pagination.

fromdatetimeOptional

Include events created at or after this timestamp.

todatetimeOptional

Include events created at or before this timestamp.

sourceenumOptional

Filter events by source: api (direct API requests), playground, compose (Compose video productions), gpu_cloud (GPU Cloud rentals), or hosted_agents (calls made by a Hosted Agent).

Allowed values:

modelstringOptional

Filter to one model ID.

statusenumOptional

Filter by request status.

Allowed values:

Response

Account balance, summary, and usage events.

objectstringOptional

balanceobjectOptional

planobjectOptional

Current subscription state. Present for an account with a current active or past-due subscription. A past-due plan grants no plan access. Allowance limits are intentionally shown on the Billing and pricing pages rather than frozen into this API schema.

summaryobjectOptional

spendobjectOptional

Account-level spend split by product over the requested window (from / to), or all-time when neither is set. This is distinct from summary, which only covers the returned page of usage events.

datalist of objectsOptional

has_morebooleanOptional

next_cursordatetime or nullOptional

Errors

401

Unauthorized Error

$	curl https://api.empiriolabs.ai/v1/account/usage \
>	-H "Authorization: Bearer <token>"