Authentication
Three lanes reach the same data. Pick the one that fits the caller:
- Session — a JWT from
POST /auth/login, for the console. - API key — an
sk_…token in theAuthorizationheader, for scripts and services. - OAuth 2.1 — access tokens for MCP and agents (authorization-code + PKCE, or client-credentials), with RFC 8414 discovery.
headerAuthorization: Bearer sk_live_…Filter vocabulary
The telemetry endpoints share one query language: a time window (from/to, defaulting to the last 24h), service, severity/status, free-text q, trace_id/span_id, and sort. A stats endpoint accepts the same filters as its list, so a chart and its underlying rows always agree.
Telemetry
| Endpoint | Returns |
|---|---|
GET /telemetry/service | Cross-signal service inventory, unhealthiest first |
GET /telemetry/log · /log/stats | Log records and aggregations |
GET /telemetry/trace · /trace/stats | Spans and aggregations |
GET /telemetry/metric | Metric series |
Cost, AI, and the graph
| Endpoint | Returns |
|---|---|
GET /cost · /cost/stats | Billed spend from the ledger, by provider/service/day, with coverage |
GET /ai/usage · /ai/cost · /ai/trace | AI adoption, billed-first AI spend, and gen_ai call spans |
GET /entity · /entity/:id/blast | Graph entities and blast radius |
GET /incident | Incidents with their timeline and connected entities |
Monitors
Monitors are the write surface. Create or tune with POST /monitor, run one now with POST /monitor/:id/run, mute or retire with a state change or DELETE. The same verbs are exposed to agents as MCP tools — see the MCP server.
Example
curlcurl "https://api.byteshift.com/telemetry/log/stats?service=checkout-api&severity=ERROR&from=2026-07-01T00:00:00Z" \
-H "Authorization: Bearer sk_live_…"Prefer to let an agent drive? The MCP server wraps this surface in intent-shaped tools, so you rarely hand-write these queries.