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.
| Need | Read |
|---|---|
| Cost of the call you just made | usage.cost on the response |
| One request later | GET /api/v1/generation?id= |
| Balance | GET /api/v1/credits |
| Billing sync, per request | GET /api/v1/usage |
| One key's full window as a file | POST /api/v1/usage/exports |
| Filterable request log with prompts | GET /api/orgs/{org_id}/usage/requests |
| Daily or per-model rollups | GET /api/gateway/usage/daily |
| Exact grouped reports, CSV (provisioning key) | Spend API, POST /api/orgs/{org_id}/spend/analytics |
/api/v1/usageGET/api/v1/creditscurl https://api.experientiallabs.ai/api/v1/credits \
-H "Authorization: Bearer YOUR_API_KEY"
# {"data": {"total_credits": 120.0, "total_usage": 37.42}} remaining = credits - usageCost 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).
/api/v1/generationraw = 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.
| Field | Meaning |
|---|---|
real_cost_usd | Charged credits plus BYOK pass-through; 0 with pricing_known: false means unpriced, not free |
cost_usd | Charged platform credits |
estimated_cost_usd | Estimated or attributed cost |
input_tokens, output_tokens, cached_input_tokens, reasoning_tokens | Tokens |
id, created_at, model, provider, status, api_key_id, attribution_label | Identity |
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_afterDownload 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).
/api/v1/usage/exportsGET/api/v1/usage/exports/{export_id}GET/api/v1/usage/exports/{export_id}/downloadcurl -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.
| Parameter | Values |
|---|---|
window / start, end | 24h, 7d (default), 30d, or an exact ISO range |
status | error (anything not completed) or completed, failed, cancelled, incomplete |
model, api_key_id, attribution_label, lane (platform, byok), failure_class, cache_hits_only | Filters |
sort | time (default), oldest, cost, latency, tokens |
limit | 1 to 200 (default 50) |
One request: add include_body=true for messages, request settings and response; /attempts lists every provider dispatch.
/api/orgs/{org_id}/usage/requestsGET/api/orgs/{org_id}/usage/requests/{request_id}GET/api/orgs/{org_id}/usage/requests/{request_id}/attemptscurl "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.
/api/gateway/usage/dailyGET/api/gateway/usage/eventsGET/api/orgs/{org_id}/usage/timeseriesGET/api/orgs/{org_id}/usage/latencycurl "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.
/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}