HTTP API Reference - VoiceGateway

The VoiceGateway HTTP API runs via voicegw serve (default port 8080). It provides read-only observability endpoints and full CRUD for managing providers, models, and projects. Start the server:

voicegw serve --port 8080

Health

GET /health

Returns the health status and uptime of the gateway. Response:

{
  "status": "ok",
  "uptime_seconds": 3621.4,
  "version": "0.1.0"
}

Example:

curl http://localhost:8080/health

Status and Models

GET /v1/status

Returns the configuration status of all providers and high-level counts. Response:

{
  "providers": {
    "deepgram": { "configured": true, "type": "cloud" },
    "openai": { "configured": true, "type": "cloud" },
    "whisper": { "configured": true, "type": "local" }
  },
  "model_count": 8,
  "project_count": 3
}

Example:

curl http://localhost:8080/v1/status

GET /v1/models

List all registered models across all modalities. Query parameters:

Parameter	Type	Default	Description
`project`	`string`	`null`	If set, filters to models used by this project’s default stack.

Response:

{
  "models": {
    "deepgram/nova-3": {
      "modality": "stt",
      "provider": "deepgram",
      "model": "nova-3"
    },
    "openai/gpt-4o-mini": {
      "modality": "llm",
      "provider": "openai",
      "model": "gpt-4o-mini"
    }
  },
  "project": null
}

Example:

curl http://localhost:8080/v1/models
curl "http://localhost:8080/v1/models?project=tonys-pizza"

Costs and Latency

GET /v1/costs

Return cost summary for a period, optionally filtered by project. Query parameters:

Parameter	Type	Default	Description
`period`	`string`	`"today"`	One of: `today`, `week`, `month`, `all`.
`project`	`string`	`null`	Filter by project ID.

Response:

{
  "period": "today",
  "project": null,
  "total": 1.2345,
  "by_provider": {
    "deepgram": { "cost": 0.5123, "requests": 42 },
    "openai": { "cost": 0.7222, "requests": 18 }
  },
  "by_model": {
    "deepgram/nova-3": { "cost": 0.5123, "requests": 42 }
  },
  "by_project": {
    "tonys-pizza": { "cost": 0.8100, "requests": 35 }
  }
}

Example:

curl "http://localhost:8080/v1/costs?period=week"
curl "http://localhost:8080/v1/costs?period=month&project=tonys-pizza"

GET /v1/latency

Return latency statistics for the given period. Query parameters:

Parameter	Type	Default	Description
`period`	`string`	`"today"`	One of: `today`, `week`, `month`.
`project`	`string`	`null`	Filter by project ID.

Response: Per-model latency statistics including average TTFB and total latency. Example:

curl "http://localhost:8080/v1/latency?period=today"
curl "http://localhost:8080/v1/latency?period=week&project=my-app"

Sessions

One row per voice call: when it started and ended, which modalities and providers it used, and what it cost. These are the public twin of the dashboard’s /api/sessions reads and return the same rows; the Dashboard API additionally serves the per-session drill-downs (turns, transcript, dead air, replay). Authentication: both routes require the same read authentication as the dashboard reads, declared on the router so no route can miss it. The gate is a no-op while no API keys are configured (the self-hosted default: no auth.api_keys block and no VOICEGW_API_KEY), and it enforces as soon as auth is enabled, when an unauthenticated request gets 401. A read-scoped key is enough; no admin scope is needed to read rows already on disk. Tenant scoping: the tenant comes from the authenticated key, never from a parameter (these routes publish none). A tenant-scoped key lists only its own sessions and reads only its own session by id. The list filters as well as the detail: a list that returned every tenant’s sessions would hand over exactly the ids the detail route refuses. An operator with no credential, a static config key, or an admin key sees every tenant, unchanged.

Response	Meaning
`401`	Auth is enabled and the request carried no token, or an invalid one.
`404`	No such session or the session belongs to another tenant. The two are deliberately identical, body included: a `403` on the foreign case would confirm the id is real.

GET /v1/sessions

Return recent sessions. Query parameters:

Parameter	Type	Default	Description
`limit`	`integer`	`100`	Number of rows (1-1000).
`project`	`string`	`null`	Filter by project ID.
`order_by`	`string`	`"started_at_desc"`	One of: `started_at_desc`, `started_at_asc`, `cost_desc`, `cost_asc`.

Response: An array of session rows, each containing id, project, started_at, ended_at, modalities, request_count, total_cost_usd, and tenant_id. Empty array when cost tracking is disabled.

GET /v1/sessions/

Return one session with the per-modality cost breakdown (by_modality) and the deduplicated providers list computed by joining the requests table. Example:

curl "http://localhost:8080/v1/sessions?limit=20&order_by=cost_desc"
curl "http://localhost:8080/v1/sessions/vg-8f1c"

Rooms

The per-stage latency split for one LiveKit room, over HTTP. The same split is available in-process to voicegw livekit latency, but only when the prober and the agent share one local store. A deployment that runs the agent in one container and the collector in another holds every row needed and cannot reach the computation. This endpoint is that computation, reachable. No new measurement happens here. Keyed on the room name, deliberately, not on session_id. A caller mints the room name when it signs the LiveKit token, so the room is the only identifier both sides hold at call time; session_id is minted inside VoiceGateway and a caller never observes it. Authentication: read authentication, the same as Sessions. Tenant comes from the key and never from the request.

GET /v1/rooms//latency

Query parameters:

Parameter	Type	Default	Description
`since_turn`	`integer`	`null`	Return only turns whose room-wide `seq` is greater than this. Filters `turns` only.

since_turn is a cursor over turns and nothing else. It cuts on seq, the room-wide position, not on turn_index: turn_index is session-local, so a room carrying more than one session has two turns numbered 0, two numbered 1, and so on. Pass back the seq of the last turn you saw. components and e2e_ms are whole-call aggregates and are never narrowed by since_turn. They are recomputed from the rows present at request time, so they do move as a call progresses and successive polls will differ; what since_turn guarantees is only that it is not the thing moving them. Four answers that mean different things:

Response	Meaning
`404`	This collector has never seen that room, or the room belongs to another tenant. Identical on purpose: a `403` would confirm the room is real.
`200`, `components: null`	The room is known and nothing correlated: an uninstrumented agent, or no completed turn yet.
`200`, `complete: false`	A real split, still partial because the agent process is mid-flush. Poll again rather than rendering it.
`200`, a component is `null`	That stage produced no measurement. It is never `0`: a stage shown as `0.00` reads as “instant”.

Every value is in milliseconds, but of two different kinds, and the field names do not distinguish them:

Epoch timestamps (a point in time): caller_speak_end_ms, agent_speak_start_ms. Unix epoch, milliseconds.
Elapsed durations (a length of time): response_speed_ms, every member of components, and every member of e2e_ms.

Example:

curl -H "Authorization: Bearer vk_..." \
  "http://localhost:8080/v1/rooms/demo-a1b2c3/latency?since_turn=5"

{
  "room": "demo-a1b2c3",
  "project": "pixis-w1",
  "turn_count": 7,
  "complete": true,
  "components": {
    "eou_ms": 302.0,
    "stt_ttfp_ms": 121.0,
    "stt_transcription_delay_ms": 88.0,
    "stt_ms": 209.0,
    "llm_ttft_ms": 447.0,
    "tts_ttfb_ms": 92.0
  },
  "e2e_ms": {
    "p50": 1041.0, "p95": 1288.0, "avg": 1074.0,
    "min": 902.0, "max": 1301.0, "n": 7
  },
  "turns": [
    {
      "seq": 6,
      "turn_index": 6,
      "session_id": "vg-8f1c",
      "caller_speak_end_ms": 1800000012345,
      "agent_speak_start_ms": 1800000013386,
      "response_speed_ms": 1041
    }
  ]
}

e2e_ms is computed by the same summarize() the CLI reports through, so the two surfaces cannot drift on what p95 means. It is null, rather than a row of zeros, when no turn carries a measured response_speed_ms. That is not the same as “no turns”: turn_count can be non-zero while e2e_ms is null. A turn the agent never answered records a null response_speed_ms, and such turns are listed in turns but contribute no sample. Averaging them in as 0 would drag every percentile down and report a call as faster than it was. Not provided, on purpose: no CORS and no browser-facing key (a read-scoped key in a browser can read every session and cost row for the tenant, so proxy it server-side); no WebSocket or SSE (ingest is batched behind a bounded queue, so freshness is inherently seconds, and a socket would deliver seconds-stale data faster while adding a stateful fan-out surface); no per-turn component split.

Billing

The rating layer’s read surface. VoiceGateway rates each recorded request at write time (rated_price_usd + rate_rule); these endpoints roll that up per tenant and expose the rate card in effect. See Rating for the model.

GET /v1/billing/usage

Return rated revenue, recorded cost, and margin per tenant for a window. Query parameters:

Parameter	Type	Default	Description
`period`	`string`	`"month"`	One of: `today`, `week`, `month`.
`start`	`string`	`null`	Start date in `YYYY-MM-DD`.
`end`	`string`	`null`	End date in `YYYY-MM-DD` (inclusive day).
`project`	`string`	`null`	Filter by project ID.
`tenant`	`string`	`null`	Filter to a single tenant. When set, the response also includes `line_items`.

Response:

{
  "period": "month",
  "start": null,
  "end": null,
  "tenant": null,
  "tenants": [
    {
      "tenant_id": "acme",
      "requests": 120,
      "cost_usd": 0.48,
      "rated_usd": 0.72,
      "margin_usd": 0.24,
      "margin_pct": 33.3
    }
  ],
  "totals": {
    "requests": 120,
    "cost_usd": 0.48,
    "rated_usd": 0.72,
    "margin_usd": 0.24
  }
}

When tenant is passed, the response also carries that tenant’s per-(modality, model) line items for invoice detail:

{
  "line_items": [
    {
      "modality": "stt",
      "model_id": "deepgram/nova-3",
      "provider": "deepgram",
      "requests": 120,
      "input_units": 45.0,
      "output_units": 0.0,
      "cost_usd": 0.48,
      "rated_usd": 0.72,
      "margin_usd": 0.24
    }
  ]
}

Example:

curl "http://localhost:8080/v1/billing/usage?period=month"
curl "http://localhost:8080/v1/billing/usage?tenant=acme&start=2026-06-01&end=2026-06-30"

GET /v1/billing/rate-card

Return the rate card in effect: the global default markup plus every rule, merging the rate_card: YAML seed with the DB overrides. The rule field on each rule is the audit token stamped onto matching requests (for example cost_plus:1.3 or fixed:0.006/minute). Response:

{
  "default_markup": 1.0,
  "rules": [
    {
      "modality": "stt",
      "provider": "deepgram",
      "model": "nova-3",
      "tenant": null,
      "plan": null,
      "kind": "fixed",
      "markup": null,
      "unit_price_usd": 0.006,
      "unit": "minute",
      "rule": "fixed:0.006/minute"
    }
  ]
}

Example:

curl http://localhost:8080/v1/billing/rate-card

GET /v1/billing/rate-card/models

Distinct models seen in telemetry, each with its voice-prices unit cost and the rate rule that currently applies to it. Lets an operator spot stale prices and see which rule matches a model without cross-referencing /rate-card/rules by hand. Response:

{
  "models": [
    {
      "modality": "stt",
      "provider": "deepgram",
      "model": "nova-3",
      "unit": "minute",
      "voice_price_usd": 0.0043,
      "effective": {
        "modality": "stt",
        "provider": "deepgram",
        "model": "nova-3",
        "kind": "fixed",
        "unit_price_usd": 0.006,
        "unit": "minute",
        "rule": "fixed:0.006/minute"
      }
    }
  ]
}

unit is the canonical unit voice_price_usd is priced per: minute for STT, 1k_char for TTS, 1m_token for LLM. voice_price_usd is null when the model is not in the voice-prices catalog. effective is the matching rate-card rule (seed or DB override), or null when no explicit rule matches and the default markup applies. Example:

curl http://localhost:8080/v1/billing/rate-card/models

GET /v1/billing/rate-card/rules

Return the editable DB override rules, each with its rule_id. Use this to drive an editor (the seed rules in GET /rate-card have no rule_id; only DB overrides are mutable).

POST /v1/billing/rate-card/rules

Upsert a DB rate-card override for a scope (one rule per scope, keyed by tenant|plan|modality|provider|model). Requires the write scope. Takes effect on the next config refresh, which the call triggers. Body: a scope (modality?, provider?, model?, tenant?, plan?) plus either markup (cost-plus) or fixed + unit.

curl -X POST http://localhost:8080/v1/billing/rate-card/rules \
  -H "Authorization: Bearer $VG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant": "acme", "provider": "deepgram", "markup": 1.1}'
# -> {"rule_id": "acme|*|*|deepgram|*", "created": true}

A rule that sets both markup and fixed, or a fixed rule with a missing/invalid unit, returns 400.

DELETE /v1/billing/rate-card/rules/

Delete a DB override by its rule_id (from GET /rate-card/rules). Requires the write scope. Returns 404 when no rule has that id.

The rate card is one store, edited three ways: the rate_card: seed in voicegw.yaml, the CLI (voicegw prices set / rm), and these HTTP endpoints (which the dashboard Rate card page under Configure also uses). See Rating.

Projects

GET /v1/projects

List all configured projects with today’s stats. Response:

{
  "projects": [
    {
      "id": "tonys-pizza",
      "name": "Tony's Pizza",
      "description": "Pizza ordering voice agent",
      "daily_budget": 10.0,
      "default_stack": "premium",
      "tags": ["production"],
      "accent": "#e74c3c"
    }
  ],
  "stats": {
    "tonys-pizza": {
      "cost_today": 2.45,
      "requests_today": 120
    }
  }
}

Example:

curl http://localhost:8080/v1/projects

GET /v1/projects/

Return full details for a single project including today’s spend and budget status. Response:

{
  "id": "tonys-pizza",
  "name": "Tony's Pizza",
  "description": "Pizza ordering voice agent",
  "daily_budget": 10.0,
  "budget_action": "warn",
  "default_stack": "premium",
  "tags": ["production"],
  "accent": "#e74c3c",
  "today_spend": 2.45,
  "budget_status": "ok",
  "today": { "cost_today": 2.45, "requests_today": 120 },
  "costs_today": { "total": 2.45, "by_provider": {}, "by_model": {} }
}

Example:

curl http://localhost:8080/v1/projects/tonys-pizza

POST /v1/projects

Create a new project (stored in SQLite). Request body:

{
  "project_id": "new-app",
  "name": "New App",
  "description": "A new voice agent",
  "daily_budget": 5.0,
  "budget_action": "warn",
  "default_stack": "premium",
  "tags": ["staging"]
}

Response:

{
  "project_id": "new-app",
  "source": "db",
  "created": true
}

Example:

curl -X POST http://localhost:8080/v1/projects \
  -H "Content-Type: application/json" \
  -d '{"project_id":"new-app","name":"New App","daily_budget":5.0}'

PATCH /v1/projects/

Update a managed project. Only projects created via the API (source "db") can be updated. Request body: Any subset of fields from the POST body. Response:

{
  "project_id": "new-app",
  "updated": true
}

Example:

curl -X PATCH http://localhost:8080/v1/projects/new-app \
  -H "Content-Type: application/json" \
  -d '{"daily_budget":10.0}'

DELETE /v1/projects/

Delete a managed project. Requires ?confirm=true to actually delete. Without the parameter, returns a preview of what would be deleted. Query parameters:

Parameter	Type	Default	Description
`confirm`	`boolean`	`false`	Must be `true` to perform the deletion.

Response (preview):

{
  "would_delete": { "project_id": "new-app" }
}

Response (confirmed):

{
  "deleted": "new-app"
}

Example:

# Preview
curl -X DELETE "http://localhost:8080/v1/projects/new-app"
# Confirm
curl -X DELETE "http://localhost:8080/v1/projects/new-app?confirm=true"

YAML-defined projects cannot be deleted via the API. A 403 is returned.

Providers

GET /v1/providers

List all providers (YAML-defined and managed). Response:

{
  "providers": [
    {
      "provider_id": "deepgram",
      "source": "yaml",
      "api_key_masked": "sk-a...1f2b",
      "base_url": null
    }
  ]
}

Example:

curl http://localhost:8080/v1/providers

POST /v1/providers

Add a new provider (stored in SQLite). The provider type must be one of the supported types. Request body:

{
  "provider_id": "deepgram-staging",
  "provider_type": "deepgram",
  "api_key": "sk-your-api-key",
  "base_url": null
}

Response:

{
  "provider_id": "deepgram-staging",
  "source": "db",
  "api_key_masked": "sk-y...key"
}

Example:

curl -X POST http://localhost:8080/v1/providers \
  -H "Content-Type: application/json" \
  -d '{"provider_id":"deepgram-staging","provider_type":"deepgram","api_key":"sk-your-key"}'

PATCH /v1/providers/

Update a managed provider’s API key, base URL, or type. Omitted fields keep their stored value, so a body of {"api_key":"sk-new-key"} rotates the key and leaves base_url alone. Example:

curl -X PATCH http://localhost:8080/v1/providers/deepgram-staging \
  -H "Content-Type: application/json" \
  -d '{"api_key":"sk-new-key"}'

Moving base_url to a new host A request that changes base_url without supplying an api_key keeps the stored key, and POST /v1/providers/{provider_id}/test then sends that key to the new host. So that one combination requires the new host to be permitted. Permitted are the provider’s current host, the vendor’s own default host (api.openai.com for openai, localhost for ollama, and so on), and any host listed in serve.provider_base_url_hosts in voicegw.yaml. An unpermitted host returns 400 naming the config key:

{
  "detail": "base_url host 'proxy.internal.example.com' is not permitted for provider 'deepgram-staging'. Moving base_url to a new host while reusing the stored API key would send that key to the new host. Add the host to 'serve.provider_base_url_hosts' in voicegw.yaml, or send a fresh 'api_key' in this request."
}

Sending the key with the change is always allowed, because the caller already holds a key:

curl -X PATCH http://localhost:8080/v1/providers/deepgram-staging \
  -H "Content-Type: application/json" \
  -d '{"base_url":"https://proxy.internal.example.com","api_key":"sk-new-key"}'

Requests that keep the same host (port or path edits), clear base_url, or leave it untouched are unaffected, as are providers stored with an empty key such as a local ollama.

DELETE /v1/providers/

Delete a managed provider. Requires ?confirm=true. Query parameters:

Parameter	Type	Default	Description
`confirm`	`boolean`	`false`	Must be `true` to perform the deletion.

Example:

# Preview
curl -X DELETE "http://localhost:8080/v1/providers/deepgram-staging"
# Confirm
curl -X DELETE "http://localhost:8080/v1/providers/deepgram-staging?confirm=true"

POST /v1/providers//test

Test connectivity to a provider by running its health check. Response:

{
  "status": "ok",
  "latency_ms": 142
}

Example:

curl -X POST http://localhost:8080/v1/providers/deepgram/test

POST /v1/providers/test

Test connectivity for a provider type + credential before saving it, for an “add provider” form that wants to validate a key first. Unlike the route above, this takes no provider_id: nothing has to exist yet. Request body:

{
  "provider_type": "deepgram",
  "api_key": "sk-your-api-key",
  "base_url": null
}

Response: same shape as POST /v1/providers/{provider_id}/test: {"status": "ok" | "failed", "latency_ms": <int>, "message"?: <str>}. Example:

curl -X POST http://localhost:8080/v1/providers/test \
  -H "Content-Type: application/json" \
  -d '{"provider_type":"deepgram","api_key":"sk-your-api-key"}'

Models

POST /v1/models

{
  "modality": "stt",
  "provider_id": "deepgram",
  "model_name": "nova-3",
  "display_name": "Deepgram Nova 3",
  "default_language": "en"
}

Response:

{
  "model_id": "deepgram/nova-3",
  "source": "db",
  "created": true
}

Example:

curl -X POST http://localhost:8080/v1/models \
  -H "Content-Type: application/json" \
  -d '{"modality":"stt","provider_id":"deepgram","model_name":"nova-3"}'

DELETE /v1/models/

Delete a managed model. Requires ?confirm=true. The model_id is a path parameter (for example, deepgram/nova-3). Example:

# Preview
curl -X DELETE "http://localhost:8080/v1/models/deepgram/nova-3"
# Confirm
curl -X DELETE "http://localhost:8080/v1/models/deepgram/nova-3?confirm=true"

Logs and Metrics

GET /v1/logs

Return recent request logs. Query parameters:

Parameter	Type	Default	Description
`limit`	`integer`	`100`	Number of rows (1-1000).
`modality`	`string`	`null`	Filter: `stt`, `llm`, or `tts`.
`project`	`string`	`null`	Filter by project ID.

Response: An array of log records, each containing timestamp, project, modality, model_id, cost_usd, total_latency_ms, status. Example:

curl "http://localhost:8080/v1/logs?limit=20&modality=stt"
curl "http://localhost:8080/v1/logs?project=tonys-pizza&limit=50"

GET /v1/metrics

Return Prometheus-format metrics (plain text). Response (text/plain):

# HELP voicegw_uptime_seconds Process uptime
# TYPE voicegw_uptime_seconds gauge
voicegw_uptime_seconds 3621.4
# HELP voicegw_providers_configured Configured providers
# TYPE voicegw_providers_configured gauge
voicegw_providers_configured 5
# HELP voicegw_cost_usd_total USD cost summed over a ROLLING trailing 24 hours (now-86400s to now). This is a gauge despite the _total suffix: it DECREASES as requests age out of the window. It is not a since-start total and not a calendar day. Do not use rate() or increase() on it.
# TYPE voicegw_cost_usd_total gauge
voicegw_cost_usd_total{period="today"} 1.234500
# TYPE voicegw_requests_total gauge
voicegw_requests_total{provider="deepgram"} 42
voicegw_cost_usd_total{provider="deepgram"} 0.512300
# HELP voicegw_diag_gate_status Health gates in the newest stored LiveKit diagnostics run, counted by gate id and status.
# TYPE voicegw_diag_gate_status gauge
voicegw_diag_gate_status{gate="agents_listing",status="PASS"} 1
voicegw_diag_gate_status{gate="agent_reply_latency",status="UNKNOWN"} 2
# TYPE voicegw_diag_run_verdict gauge
voicegw_diag_run_verdict{verdict="UNKNOWN"} 1
# TYPE voicegw_diag_run_timestamp_seconds gauge
voicegw_diag_run_timestamp_seconds 1785412800.000

This endpoint exposes VoiceGateway’s own numbers so your Prometheus can scrape it. It is the opposite direction from the node scrape, which pulls exposition text from livekit-server and node_exporter into this database; nothing scraped from another process is served back out here. Turning the node scrape on. That inbound scrape is off unless you name targets. Set VOICEGW_NODE_SCRAPE_TARGETS to a comma-separated list of source:name=url entries before starting the collector:

export VOICEGW_NODE_SCRAPE_TARGETS="livekit-server:sfu-1=http://10.0.0.4:6789/metrics,node-exporter:sfu-1=http://10.0.0.4:9100/metrics"

source is one of livekit-server, livekit-sip or node-exporter. name is the node the samples are filed under, and using the same name for two sources is the point: it puts an SFU’s own counters and its host’s file descriptors on one time axis. A malformed entry is skipped with a warning instead of failing startup, and the collector logs how many targets it read. An endpoint behind basic auth takes the credential in the URL, the usual way:

export VOICEGW_NODE_SCRAPE_TARGETS="livekit-server:sfu-1=http://user:secret@10.0.0.4:6789/metrics"

The credential is split off the URL when the variable is parsed and sent as an Authorization header instead. That matters because the HTTP client logs its request line at INFO: left in the URL, the password would be written to the log on every tick, four times a minute, for as long as the collector runs. Nothing logs it now, including the warning about a malformed entry, which prints the host with the credential replaced by ***. Percent-encode a password containing @, : or /. With the variable unset or empty no scrape worker is started and the collector makes no outbound requests, which is the default. Cadence comes from workers.node_scrape_interval_seconds in voicegw.yaml (default 15 seconds, matching Prometheus’ own default); workers.enabled: false disables this worker along with the rollups. voicegw_cost_usd_total and voicegw_requests_total are gauges over a rolling 24-hour window, not counters. Both are computed from the "today" window, which is now - 86400 seconds: a rolling trailing 24 hours. It is not midnight-to-now and not a since-process-start total. The value therefore goes down as well as up, every time a request falls off the trailing edge. The period="today" label and the _total suffix are both misnomers kept for backward compatibility, because renaming a scraped series would break every dashboard already built on it. The # TYPE metadata is now gauge, which is what your tooling actually reads. Concretely, this means:

# WRONG. rate()/increase() require a counter. Every decrease (a request ageing
# out of the 24h window) is read as a counter reset, and Prometheus extrapolates
# spend and traffic that never happened.
rate(voicegw_cost_usd_total[5m])
increase(voicegw_requests_total[1h])

# RIGHT. Read the gauge as-is, or aggregate/compare it over time.
voicegw_cost_usd_total{period="today"}                    # spend in the last 24h
sum(voicegw_requests_total)                               # requests in the last 24h
delta(voicegw_cost_usd_total{period="today"}[1h])         # how the 24h window moved
max_over_time(voicegw_cost_usd_total{period="today"}[7d]) # worst 24h in a week

sum(voicegw_requests_total) sums the per-provider series; there is no separate unlabelled total. Do not write bare sum(voicegw_cost_usd_total): that series is emitted three times over, once with period="today", once per provider and once per project, so an unfiltered sum counts the same spend about three times. Always select a label set. For an actual monotonic spend counter (one that supports rate() and increase()), VoiceGateway does not publish one yet. Use GET /v1/costs?period=all, which is a true since-start total, or period=week / period=month for wider rolling windows. The latency series (voicegw_request_ttfb_seconds, voicegw_request_total_latency_seconds) are summary quantiles over the same rolling trailing 24 hours. Summary quantiles were never counters, so their type is unchanged; no _sum or _count children are published, so there is nothing to rate() there either. Diagnostics gate series. voicegw_diag_gate_status reports the health gates of the newest stored diagnostics run that gated anything, aggregated per gate id and status: the probed agent is not a label, so cardinality does not grow with your fleet. Statuses are the one ladder voicegw livekit check uses, PASS < WARN < UNKNOWN < FAIL, where UNKNOWN means the gate could not be evaluated and is not a pass (only PASS exits 0). voicegw_diag_run_verdict is that run’s stored verdict, and voicegw_diag_run_timestamp_seconds is when it finished, so a clean verdict from three weeks ago is distinguishable from one from a minute ago. Unknown values are omitted, never zero. No diagnostics run, no readable diagnostics table, or a status this build does not recognise means the series is absent. A 0 would be a real observation and would be alerted on; absence is the honest reading. Alert on what is there (for example voicegw_diag_gate_status{status!="PASS"} > 0) and on absent(...) if you require a run to have happened. Example:

curl http://localhost:8080/v1/metrics
curl -s http://localhost:8080/v1/metrics | grep voicegw_diag_gate_status

Audit Log

GET /v1/audit-log

Return audit log entries for CRUD operations performed via the API. Query parameters:

Parameter	Type	Default	Description
`limit`	`integer`	`50`	Number of entries (1-500).
`entity_type`	`string`	`null`	Filter: `provider`, `model`, or `project`.
`entity_id`	`string`	`null`	Filter by specific entity ID.
`action`	`string`	`null`	Filter: `create`, `update`, or `delete`.

Response: An array of audit log entries. Example:

curl "http://localhost:8080/v1/audit-log?entity_type=provider&limit=10"
curl "http://localhost:8080/v1/audit-log?action=delete"

API Keys

Mint, list, and revoke the virtual keys (vk_...) that authenticate callers of this API. Authentication: every route under /v1/api-keys requires the admin scope, declared on the router so no route can miss it. Like Diagnostics, the gate is a no-op while no API keys are configured (the self-hosted default: no auth.api_keys block and no VOICEGW_API_KEY), and it enforces the admin scope as soon as auth is enabled. Pass a static key carrying admin or the * wildcard scope, or an admin-role vk_ key: Authorization: Bearer .... This gate matters because a minted key is issued with the wildcard scope. An ungated mint is a write escalation onto every /v1 endpoint, so an unauthenticated caller must not reach it. A key minted here defaults to role: tenant, which means a minted key cannot mint another key (403): a leaked key is not self-replicating.

Response	Meaning
`401`	Auth is enabled and the request carried no token, or an invalid one.
`403`	Valid token without the `admin` scope, or a `vk_` key whose role is not `admin`.

POST /v1/api-keys

Mint a virtual key. Body: name (required), tenant_id (optional, binds the key to one tenant), issued_by (optional audit string). Returns 201 with plaintext (the only time the full key is ever returned) and the stored key row. The bcrypt hash is never exposed.

curl -X POST http://localhost:8080/v1/api-keys \
  -H "Authorization: Bearer $VG_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-bot", "tenant_id": "acme"}'

GET /v1/api-keys

List every key. include_revoked (default true) keeps soft-revoked rows in the response. Rows carry key_prefix, never the hash or the plaintext.

GET /v1/api-keys/

Fetch one key by id. 404 when missing.

DELETE /v1/api-keys/

Soft-revoke a key. The row stays for audit with revoked_at set. Returns 204.

LiveKit Webhooks

POST /v1/livekit/webhook

Receive LiveKit room and participant lifecycle webhooks and record them as calls. This is what makes a call that runs no inference visible: a calls row and its call_legs are written from webhook events alone, so a call that never reached an LLM still exists in the schema. Point your LiveKit project’s webhook URL at this endpoint. It must be publicly reachable, since LiveKit posts to it. Authentication: the LiveKit webhook signature, not a bearer token. LiveKit cannot send a VoiceGateway API key, so the signature is the auth boundary. The request is verified against your LiveKit API key and secret before the body is parsed, and the endpoint fails closed: with no LiveKit credentials configured it returns 503 and writes nothing, rather than accepting unsigned writes.

Response	Meaning
`200`	Verified and recorded (or a known-but-unhandled event type, which is ignored).
`401`	Missing, malformed, or invalid signature. Nothing was written.
`503`	No LiveKit credentials configured, so the signature cannot be verified.

Events recorded: room_started, room_finished, participant_joined, participant_left, participant_connection_aborted, track_published, track_unpublished. Egress and ingress events are accepted and ignored. Delivery is neither ordered nor exactly-once, so every write is an idempotent upsert keyed on room_sid (and participant_sid for legs). Any event can create the call row, including a participant_left that arrives first. What this gives you: disconnect_reason from LiveKit includes real layer-1 failure causes, so a SIP_TRUNK_FAILURE, USER_UNAVAILABLE, or USER_REJECTED becomes readable per leg. Configuration: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET (or the livekit: block in voicegw.yaml). Set VOICEGW_LOADTEST_TRUNK_IDS to a comma-separated list of SIP trunk ids to mark calls arriving on those trunks as probe traffic, so load tests never pollute production percentiles.

Call Observations

POST /v1/calls/observations

Record what only a participating process can see. LiveKit sends no track_subscribed webhook, and webhook timestamps are whole seconds, so the agent’s own clock is the only source of a millisecond-precision “I published audio at T” for the call: the timestamp that gates the caller’s ring time, because livekit-sip withholds 200 OK until it subscribes to an audio track. An agent (or a load worker) posts its own view here; it merges into the same calls and call_legs rows the webhook receiver writes. Authentication: a VoiceGateway API key with the write scope (Authorization: Bearer vk_..., or a static key from auth.api_keys). Unlike the LiveKit webhook, the caller here is your own agent, which already carries VOICEGW_API_KEY. tenant_id is taken from the key, never from the body. This endpoint does not wait for the database. The report is validated, queued, and answered; a single background flusher writes it. That is deliberate: the hook runs in the agent’s job-start path, so a synchronous write would add latency to the exact number being reported. The queue is bounded at 1000 reports and drops the newest report when it is full rather than blocking the agent or growing without limit.

Response	Meaning
`202`	Queued. Not yet written.
`429`	The queue is full and this report was dropped. Do not retry: retrying makes the overload worse.
`401` / `403`	Missing/invalid key, or a key without the `write` scope.
`422`	The body carried an unknown field, a timestamp that is not in milliseconds, or no `room_sid`/`attempt_id`.
`503`	The path is disabled (`VG_DISABLE_CALL_OBSERVATIONS`), or this collector has no call storage.

Both the 202 and the 429 body carry the counters, so a reporter can see the loss:

{ "status": "queued", "queue_depth": 3, "dropped_total": 0 }

Example:

curl -X POST http://localhost:8080/v1/calls/observations \
  -H "Authorization: Bearer vk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "agent",
    "room_sid": "RM_abc123",
    "room_name": "call-4821",
    "project": "support",
    "agent_id": "inbound-agent",
    "started_at_ms": 1800000000000,
    "legs": [
      {"participant_sid": "PA_caller", "kind": "SIP", "joined_at_ms": 1800000000100},
      {"participant_sid": "PA_agent", "kind": "AGENT", "joined_at_ms": 1800000001000,
       "first_audio_track_at_ms": 1800000003842, "audio_track_sid": "TR_1",
       "audio_codec": "audio/opus"}
    ]
  }'

Fields: origin (agent or loadgen, required), one of room_sid or attempt_id (required: a report with neither cannot be correlated), plus room_name, run_id, project, agent_id, started_at_ms, ended_at_ms, and up to 16 legs. A leg carries participant_sid (required), identity, kind (SIP/AGENT/STANDARD/INGRESS/EGRESS), joined_at_ms, left_at_ms, disconnect_reason, first_audio_track_at_ms, audio_track_sid, audio_codec. All timestamps are epoch milliseconds; a seconds- or microseconds-scale value is rejected rather than merged as a nonsense call duration. calls.channel and calls.end_reason are derived from the reported legs by the same rule the webhook uses (the call’s end reason comes from the SIP leg, because that leg is the caller). Unknown fields are rejected, not ignored (422). Silently accepting a field nothing stores would let you believe a number was recorded when it was not. So there is no per-call loss, jitter, MOS, or DTMF field (not observable, no column), no SIP response code (livekit-api exposes no ListSIPCallInfo), no is_probe (probe traffic is discriminated by a dedicated load-test trunk, never by anything on the wire), and no tenant_id. Writes are idempotent. Reports are merged with the same upserts the webhook uses, keyed on room_sid/attempt_id (and participant_sid for legs), so a re-sent report is a no-op and a report that arrives before any webhook creates the row. Configuration: set VG_DISABLE_CALL_OBSERVATIONS to any value (other than 0/false/no/off) to turn the path off: the endpoint then answers 503, queues nothing, and starts no flusher. It is read per request, so it takes effect without a restart.

Fleet

Two endpoints an agent process (not an operator) calls directly: presence for the dashboard’s Fleet/Agents view, and telemetry ingest for a self-hosted collector. Both are written by register_worker and attach(collector_url=...) / attach(heartbeat=True); you would only call them by hand when scripting a non-Python worker.

GET /v1/agents

Return the live worker roster: processes that registered via register_worker or attach(heartbeat=True) and heartbeated recently. A worker ages out of the roster 45 seconds after its last heartbeat. This is presence only (idle/busy, version, host, memory), not cost or latency telemetry. For the fleet index with cost, p95 latency, and the probe button, see GET /api/agents on the Dashboard API; the two are deliberately separate surfaces (roster vs. telemetry). Response:

{
  "workers": [
    {
      "agent_id": "order-taker",
      "agent_name": "order-taker",
      "project": "default",
      "region": null,
      "version": "0.22.3",
      "host": "ip-10-0-1-4",
      "active_sessions": 1,
      "status": "busy",
      "started_at": 1752460000.0,
      "last_seen": 1752460800.0,
      "memory_rss_bytes": 214958080,
      "memory_total_bytes": 8589934592,
      "memory_pct": 2.5
    }
  ]
}

Authentication: read scope. Tenant-scoped like the other reads: an admin/operator sees every worker, a tenant-scoped key sees only its own, and a non-admin key with no tenant maps to the unattributed bucket. There is no tenant query parameter; scoping comes entirely from the caller’s credential. Example:

curl http://localhost:8080/v1/agents

POST /v1/agents/heartbeat

Upsert the caller’s own worker presence row. This is what register_worker’s collector-mode pusher and attach(heartbeat=True) POST every 15 seconds by default when a collector_url is configured; a vk_ key can only write its own tenant (any tenant_id in the body is overridden by the authenticated key’s tenant). Request body: the worker’s presence snapshot: agent_id, agent_name, dispatch_name, status, active_sessions, version, project, tenant_id, region, host, started_at, memory_rss_bytes, memory_total_bytes, cpu_pct, ts. Response: 202 with {"status": "accepted"}. Authentication: write scope. Example:

curl -X POST http://localhost:8080/v1/agents/heartbeat \
  -H "Authorization: Bearer vk_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"order-taker","agent_name":"order-taker","status":"idle","active_sessions":0,"version":"0.22.3","project":"default","host":"ip-10-0-1-4","ts":1752460800.0}'

POST /v1/ingest

Persist a batch of request records pushed by a fleet agent’s RemoteCollectorSink (used when attach(collector_url=...) / VOICEGW_COLLECTOR_URL is set). This is the self-hosted collector’s write path; a single-node deployment with no collector_url never calls it. Request body: a JSON array of request-record dicts (not wrapped in an object). Unknown keys are ignored; a record missing required fields is skipped and counted, not rejected as a batch. Each record is re-rated against the collector’s own rate card before it is stored, so an agent-supplied rated_price_usd / rate_rule is overwritten: agents rate at cost pass-through, the collector is the source of truth for margins. See Rating. Response:

{ "accepted": 42, "duplicates": 0 }

A duplicate is a record id (UUID) already stored, from a sink retry; it is counted, not double-written. Authentication: write scope.

Status	Meaning
`413`	Batch larger than `ingest.max_batch_size` in `voicegw.yaml` (default 1000).
`429`	Ingest rate limit exceeded (`ingest.requests_per_minute` / `ingest.burst`, defaults 120/240), keyed by virtual key, else API-key hash, else client IP. Carries `Retry-After`.
`503`	Cost-tracking storage is disabled on this collector.

Example:

curl -X POST http://localhost:8080/v1/ingest \
  -H "Authorization: Bearer vk_..." \
  -H "Content-Type: application/json" \
  -d '[{"id":"...", "timestamp":1752460800.0, "modality":"stt", "provider":"deepgram", "model":"nova-3", "cost_usd":0.0021}]'

POST /v1/ingest/turns

Push a batch of conversation turns. Same bearer auth and batch cap as /v1/ingest, returns {"accepted": n}. Each object needs session_id, turn_index, caller_speak_start_ms, and caller_speak_end_ms. agent_speak_start_ms, agent_speak_end_ms, and response_speed_ms are optional. Unknown keys are ignored, and one malformed row does not reject the batch.

curl -X POST http://localhost:8080/v1/ingest/turns \
  -H "Authorization: Bearer vk_..." \
  -H "Content-Type: application/json" \
  -d '[{"session_id":"vg-123","turn_index":0,"caller_speak_start_ms":1000,"caller_speak_end_ms":2400,"agent_speak_start_ms":2847,"response_speed_ms":447}]'

A separate route rather than a record type on /v1/ingest. That handler builds a RequestRecord from every object it receives and counts anything that fails to build as malformed, so a turn posted there is answered 200 and silently dropped.Turns are always written to SQL, even where ClickHouse is configured for requests: ClickHouse has no turns table, and every reader of turns (/v1/rooms/{room}/latency, /api/sessions/{id}/turns, the session aggregates) reads from SQL.

POST /v1/ingest/dead-air

Push a batch of dead-air events. Same bearer auth and batch cap, returns {"accepted": n}. Each object needs session_id, started_at_ms, duration_ms, and threshold_used_ms. Unknown keys are ignored, and one malformed row does not reject the batch.

curl -X POST http://localhost:8080/v1/ingest/dead-air \
  -H "Authorization: Bearer vk_..." \
  -H "Content-Type: application/json" \
  -d '[{"session_id":"vg-123","started_at_ms":1752460800000,"duration_ms":4200,"threshold_used_ms":3000}]'

A separate route for the same reason as /v1/ingest/turns.

​Health

​GET /health

​Status and Models

​GET /v1/status

​GET /v1/models

​Costs and Latency

​GET /v1/costs

​GET /v1/latency

​Sessions

​GET /v1/sessions

​GET /v1/sessions/

​Rooms

​GET /v1/rooms//latency

​Billing

​GET /v1/billing/usage

​GET /v1/billing/rate-card

​GET /v1/billing/rate-card/models

​GET /v1/billing/rate-card/rules

​POST /v1/billing/rate-card/rules

​DELETE /v1/billing/rate-card/rules/

​Projects

​GET /v1/projects

​GET /v1/projects/

​POST /v1/projects

​PATCH /v1/projects/

​DELETE /v1/projects/

​Providers

​GET /v1/providers

​POST /v1/providers

​PATCH /v1/providers/

​DELETE /v1/providers/

​POST /v1/providers//test

​POST /v1/providers/test

​Models

​POST /v1/models

​DELETE /v1/models/

​Logs and Metrics

​GET /v1/logs

​GET /v1/metrics

​Audit Log

​GET /v1/audit-log

​API Keys

​POST /v1/api-keys

​GET /v1/api-keys

​GET /v1/api-keys/

​DELETE /v1/api-keys/

​LiveKit Webhooks

​POST /v1/livekit/webhook

​Call Observations

​POST /v1/calls/observations

​Fleet

​GET /v1/agents

​POST /v1/agents/heartbeat

​POST /v1/ingest

​POST /v1/ingest/turns

​POST /v1/ingest/dead-air

Health

GET /health

Status and Models

GET /v1/status

GET /v1/models

Costs and Latency

GET /v1/costs

GET /v1/latency

Sessions

GET /v1/sessions

GET /v1/sessions/

Rooms

GET /v1/rooms//latency

Billing

GET /v1/billing/usage

GET /v1/billing/rate-card

GET /v1/billing/rate-card/models

GET /v1/billing/rate-card/rules

POST /v1/billing/rate-card/rules

DELETE /v1/billing/rate-card/rules/

Projects

GET /v1/projects

GET /v1/projects/

POST /v1/projects

PATCH /v1/projects/

DELETE /v1/projects/

Providers

GET /v1/providers

POST /v1/providers

PATCH /v1/providers/

DELETE /v1/providers/

POST /v1/providers//test

POST /v1/providers/test

Models

POST /v1/models

DELETE /v1/models/

Logs and Metrics

GET /v1/logs

GET /v1/metrics

Audit Log

GET /v1/audit-log

API Keys

POST /v1/api-keys

GET /v1/api-keys

GET /v1/api-keys/

DELETE /v1/api-keys/

LiveKit Webhooks

POST /v1/livekit/webhook

Call Observations

POST /v1/calls/observations

Fleet

GET /v1/agents

POST /v1/agents/heartbeat

POST /v1/ingest

POST /v1/ingest/turns

POST /v1/ingest/dead-air