Usage & analytics
Query spend, balance, token usage, and per-request activity programmatically — grouped by model, key, member, and department.
Usage & analytics
Everything the console shows about spend is available over the API, under /control/v1. Use it to build your own dashboards, alert on burn rate, or attribute cost to a workload without instrumenting your application.
The three levels
| Level | Endpoint | Answers |
|---|---|---|
| Summary | GET /control/v1/usage/summary | How many tokens and dollars, this period |
| Grouped | GET /control/v1/usage/by-model, /by-key, /by-member, /by-department | Where the spend went |
| Per request | GET /control/v1/activity | Which request, what it cost, how it went |
Summary
curl "https://api.sference.com/control/v1/usage/summary?from=2026-10-01&to=2026-10-31" \
-H "Authorization: Bearer $SFERENCE_API_KEY"Returns token totals, cost, and request counts for the period.
Grouped breakdowns
# Spend by model
curl "https://api.sference.com/control/v1/usage/by-model?from=2026-10-01" \
-H "Authorization: Bearer $SFERENCE_API_KEY"
# Spend by API key — the per-engineer view for vibe coding
curl "https://api.sference.com/control/v1/usage/by-key?from=2026-10-01" \
-H "Authorization: Bearer $SFERENCE_API_KEY"
# Spend by team member
curl "https://api.sference.com/control/v1/usage/by-member?from=2026-10-01" \
-H "Authorization: Bearer $SFERENCE_API_KEY"
# Spend by department (for chargeback)
curl "https://api.sference.com/control/v1/usage/by-department?from=2026-10-01" \
-H "Authorization: Bearer $SFERENCE_API_KEY"Each has a CSV twin for spreadsheets and finance tooling:
/control/v1/usage/by-model.csv
/control/v1/usage/by-key.csv
/control/v1/usage/by-member.csv
/control/v1/usage/by-department.csvDaily series
GET /control/v1/usage/daily returns a per-day series for charting — the endpoint to poll for a burn-rate dashboard or an anomaly alert.
Per-request activity
GET /control/v1/activity is the request-level log: model, token counts, cost, latency, and outcome, one row per request. GET /control/v1/activity/{request_id} returns a single request in detail, and GET /control/v1/activity/models lists the models that appear in your activity.
curl "https://api.sference.com/control/v1/activity?limit=100" \
-H "Authorization: Bearer $SFERENCE_API_KEY"/control/v1/activity/export.csv streams the whole log as CSV for offline analysis.
Attribution comes from the key, not the payload
Every request is attributed to the API key that made it. That is why one key per engineer, per service, or per workload is the simplest way to get useful breakdowns — no application instrumentation, no tagging in the request body.
Billing
| Endpoint | Returns |
|---|---|
GET /control/v1/billing/summary | Current period spend, balance, and burn rate |
GET /control/v1/billing/balance | Available balance |
GET /control/v1/billing/transactions | Ledger entries — charges, top-ups, credits |
GET /control/v1/billing/topups | Top-up history |
A burn-rate alert
import requests
def check_burn_rate(threshold_usd: float = 50.0):
r = requests.get(
"https://api.sference.com/control/v1/usage/daily",
headers={"Authorization": f"Bearer {SFERENCE_KEY}"},
params={"from": today_minus(7)},
)
days = r.json()["data"]
avg = sum(d["cost_usd"] for d in days) / len(days)
if avg > threshold_usd:
alert(f"sference burn rate is ${avg:.2f}/day, above ${threshold_usd:.2f}")Streams
A stream rolls up its own tokens and cost, which is the cleanest attribution when a workload spans many requests:
GET /v1/streams/{stream_id}total_cost_micros on the stream detail is the workload's spend in millionths of a dollar.
Decisions
Realtime classification with POST /v1/decisions — ask up to 64 choice, score, or yes/no questions about one input and get calibrated probabilities back in a single call.
Build with agent frameworks
Build agent loops on sference with LangChain, the OpenAI Agents SDK, and the Anthropic Agent SDK — and pick the window each step runs on.