# Usage & analytics

> Query spend, balance, token usage, and per-request activity programmatically — grouped by model, key, member, and department.

Source: https://sference.com/docs/usage

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

```bash
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

```bash
# 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.csv
```

### Daily 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.

```bash
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

```python
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](https://sference.com/docs/guides/streams) 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.

- [Pricing](https://sference.com/docs/pricing): Rates, windows, and what counts as a token.
- [Streams](https://sference.com/docs/guides/streams): Per-workload cost rollups.
- [SferenceCode](https://sference.com/docs/sference-code): Per-engineer attribution for coding agents.