Usage and spend

Read what each request cost, your balance, the request log and settled usage exports with your API key.

このページはまだ翻訳されていません。英語版を表示しています。

Which read to use

All take an ordinary xpl_ key unless marked. Money in /api/v1 responses is USD; rollups use integer nano-USD (1_000_000_000 = $1). Billing concepts: Credits and billing.

NeedRead
Cost of the call you just madeusage.cost on the response
One request laterGET /api/v1/generation?id=
BalanceGET /api/v1/credits
Billing sync, per requestGET /api/v1/usage
One key's full window as a filePOST /api/v1/usage/exports
Filterable request log with promptsGET /api/orgs/{org_id}/usage/requests
Daily or per-model rollupsGET /api/gateway/usage/daily
Exact grouped reports, CSV (provisioning key)Spend API, POST /api/orgs/{org_id}/spend/analytics
GET/api/v1/usageGET/api/v1/credits
curl https://api.experientiallabs.ai/api/v1/credits \
  -H "Authorization: Bearer YOUR_API_KEY"
# {"data": {"total_credits": 120.0, "total_usage": 37.42}}  remaining = credits - usage

Cost of one request

usage.cost (USD charged) is on every Chat, Responses and Messages response, no flag needed; on a stream it rides the final usage chunk. BYOK reports cost: 0, is_byok: true and usage.cost_details.upstream_inference_cost. Requests sent with Idempotency-Key carry no usage.cost: treat it as optional. Later, pass the x-request-id header to /generation (org-scoped; another org's id is a 404).

GET/api/v1/generation
raw = client.chat.completions.with_raw_response.create(
    model="gpt-6-luna", messages=[{"role": "user", "content": "Hi"}])
request_id = raw.headers["x-request-id"]
r = raw.parse()
print(r.usage.model_extra.get("cost"), request_id)

Settled usage export

Newest first, cursor-paginated: the feed a billing job polls. Filters: attribution_label (the safety_identifier or user you sent), window, model, api_key_id, status, limit. Pass next_cursor's cursor_ts, cursor_id, cursor_after back as query params; null means the last page. Pull only, no webhook.

FieldMeaning
real_cost_usdCharged credits plus BYOK pass-through; 0 with pricing_known: false means unpriced, not free
cost_usdCharged platform credits
estimated_cost_usdEstimated or attributed cost
input_tokens, output_tokens, cached_input_tokens, reasoning_tokensTokens
id, created_at, model, provider, status, api_key_id, attribution_labelIdentity
import httpx

H = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"limit": 200, "attribution_label": "customer-42"}
while True:
    page = httpx.get("https://api.experientiallabs.ai/api/v1/usage", headers=H, params=params).json()
    for row in page["data"]:
        print(row["id"], row["model"], row["real_cost_usd"])
    cur = page["next_cursor"]
    if cur is None:
        break
    params.update(cur)  # cursor_ts, cursor_id, cursor_after

Download one key as a file

Queues a gzip JSONL file of every settled request for one key (start_at inclusive, end_at exclusive, timezone-aware, within the past 30 days). Send an Idempotency-Key header and reuse it when retrying the create. 202 returns the job; poll it, then /download returns a signed URL valid up to 15 minutes. One active export per org (429).

POST/api/v1/usage/exportsGET/api/v1/usage/exports/{export_id}GET/api/v1/usage/exports/{export_id}/download
curl -X POST https://api.experientiallabs.ai/api/v1/usage/exports \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8d0f3c1e-export-nov" \
  -d '{"api_key_id": "KEY_ID", "start_at": "2026-11-01T00:00:00Z", "end_at": "2026-11-08T00:00:00Z"}'
curl https://api.experientiallabs.ai/api/v1/usage/exports/EXPORT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
curl https://api.experientiallabs.ai/api/v1/usage/exports/EXPORT_ID/download \
  -H "Authorization: Bearer YOUR_API_KEY"   # {"url": "...", "expires_at": "..."}

Request log

The reads behind Observability. Any key of your org can call them, including captured prompt and response bodies, so share keys accordingly. About 10 reads per second per org; over that, 429 with Retry-After.

ParameterValues
window / start, end24h, 7d (default), 30d, or an exact ISO range
statuserror (anything not completed) or completed, failed, cancelled, incomplete
model, api_key_id, attribution_label, lane (platform, byok), failure_class, cache_hits_onlyFilters
sorttime (default), oldest, cost, latency, tokens
limit1 to 200 (default 50)

One request: add include_body=true for messages, request settings and response; /attempts lists every provider dispatch.

GET/api/orgs/{org_id}/usage/requestsGET/api/orgs/{org_id}/usage/requests/{request_id}GET/api/orgs/{org_id}/usage/requests/{request_id}/attempts
curl "https://api.experientiallabs.ai/api/orgs/ORG_ID/usage/requests?window=24h&status=error&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.experientiallabs.ai/api/orgs/ORG_ID/usage/requests/REQUEST_ID?include_body=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rollups

/api/gateway/usage/daily groups by day, day_model, model or member (hour and hour_model need from/to at most 7 days apart); spend is spend_nano_usd. /api/gateway/usage/events is the per-request stream behind it. Latency, provider and label rollups live under /api/orgs/{org_id}/usage/. Per key and per identity summaries (usage/by-key, usage/by-identity) need a provisioning key. Mint one key per workload to break spend out.

GET/api/gateway/usage/dailyGET/api/gateway/usage/eventsGET/api/orgs/{org_id}/usage/timeseriesGET/api/orgs/{org_id}/usage/latency
curl "https://api.experientiallabs.ai/api/gateway/usage/daily?org_id=ORG_ID&scope=org&group_by=day_model" \
  -H "Authorization: Bearer YOUR_API_KEY"

Spend API (provisioning key)

Exact, frozen reports that match the dashboard: totals, groups by model, key, member, end_user, provider, tag and more, plus CSV. Start with POST .../spend/analytics (refresh: false), keep the returned id, and poll GET .../spend/analytics/{id}; never re-POST on an unknown outcome. Money fields paid_nano_usd, byok_nano_usd, free_nano_usd are decimal strings. Inference keys get 403.

POST/api/orgs/{org_id}/spend/analyticsGET/api/orgs/{org_id}/spend/analytics/{analytics_id}
curl -X POST https://api.experientiallabs.ai/api/orgs/ORG_ID/spend/analytics \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"refresh": false, "query": {"start": "2026-11-01T00:00:00Z", "end": "2026-11-08T00:00:00Z",
       "time_zone": "UTC", "scope": "org", "basis": "requests", "group_by": "model",
       "filters": [], "tags": []}}'
# {"id": "...", "status": "loading"}  -> poll GET .../spend/analytics/{id}