Skip to main content

Analytics

Org-scoped call volume, latency, and estimated spend — every money figure here is derived from public provider list prices, not an invoiced amount. All endpoints are tenant-scoped the same way as the rest of the API (a JWT user sees only their org; a service key sees every org).

Call volume and latency​

curl "https://convostack.ai/api/analytics/calls-over-time?period=7d" \
  -H "Authorization: Bearer cak_live_..."

curl "https://convostack.ai/api/analytics/latency-breakdown?period=7d" \
  -H "Authorization: Bearer cak_live_..."

period accepts the usual relative windows (7d, 30d, ...); calls-over-time also accepts explicit from/to ISO timestamps instead.

Spend​

All spend endpoints accept an optional from/to ISO date window — defaults to the trailing 30 days, capped at 366 days.

curl "https://convostack.ai/api/analytics/spend/summary" \
  -H "Authorization: Bearer cak_live_..."
{
  "estimated": true,
  "window": { "from": "2026-06-29T13:53:17.216Z", "to": "2026-07-29T13:53:17.216Z" },
  "totalEstimatedUsd": 1.278291,
  "totalCalls": 9,
  "callsWithCost": 6,
  "callsMissingCost": 3,
  "avgEstimatedUsdPerPricedCall": 0.213049,
  "llmCostComposition": { "vendorReported": 5, "heuristic": 1, "unknown": 0 }
}

llmCostComposition breaks down how each call's LLM cost was derived: vendorReported (the provider returned real token usage), heuristic (estimated from text length when usage wasn't reported), or unknown.

Other breakdowns, same window params: spend/over-time (per UTC day), spend/by-agent, spend/by-provider, spend/by-model, spend/by-org (service-key only), and spend/top-calls.

Budgets​

# Read the current monthly budget + alert thresholds
curl "https://convostack.ai/api/analytics/spend/budget" \
  -H "Authorization: Bearer cak_live_..."

# Set it
curl -X POST "https://convostack.ai/api/analytics/spend/budget" \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"monthlyLimitUsd": 500, "alertThresholds": [50, 80, 100], "enabled": true}'

# Current-month spend vs budget, with alert level
curl "https://convostack.ai/api/analytics/spend/budget/status" \
  -H "Authorization: Bearer cak_live_..."

This budget is an alerting feature — reaching it does not block or pause calls. See Credits & billing for the daily credit balance check that does gate whether a call can be placed at all.

Export​

curl "https://convostack.ai/api/analytics/spend/export?format=csv" \
  -H "Authorization: Bearer cak_live_..." \
  -o spend.csv

format is json (default, the canonical payload) or csv (a file download). Calls with no priced cost yet are included with a cost_status: "missing" marker rather than being dropped or shown as $0.