Usage logs

Overview

Usage logs are the per-request record of all Speech-to-Text and Text-to-Speech traffic in your Soniox project. Each entry captures the model, audio duration, tokens, cost, timing, and an optional client_reference_id.

Use them to:

Monitor cost - track total Soniox spend, or split it per end user, tenant, or product feature using client_reference_id.
Debug a session - trace a specific request (model, duration, uuid) when a user reports an issue.
Catch anomalies - spot leaked API keys, runaway loops, or unusual user behavior through sudden usage spikes.

When a client can't be trusted to set client_reference_id (browser, mobile, third-party integrations), bind it to a temporary API key at creation - the identifier is then set server-side and cannot be overridden.

Logs are available via the GET /v1/usage-logs API.

What gets logged

Each entry captures the request's identity (uuid, model, request_scope, client_reference_id), its timing (start_time, end_time in UTC), token and audio-duration counts for input and output, and the resulting cost broken down by input/output and text/audio.

See GET /v1/usage-logs for the full schema and field types.

Only successfully completed requests are logged. Requests that fail before completion - for example, due to an invalid API key, insufficient funds, or a validation error - do not appear in usage logs.

Tracking with `client_reference_id`

client_reference_id is an optional string you attach to a request to tag its log entry. Use it when you need to know exact Soniox API usage per end-user - for billing, monitoring, or debugging.

Type: string
Max length: 256 characters

Supported on all four APIs:

Speech-to-Text WebSocket

Set in the configuration message:

{
  "api_key": "<SONIOX_API_KEY|SONIOX_TEMPORARY_API_KEY>",
  "model": "stt-rt-v4",
  "audio_format": "auto",
  "client_reference_id": "user_8f2c4b1a"
}

Speech-to-Text Async

Set in the body of POST /v1/transcriptions:

{
  "model": "stt-async-v4",
  "audio_url": "https://example.com/audio.mp3",
  "client_reference_id": "user_8f2c4b1a"
}

Text-to-Speech WebSocket

Set in the stream configuration message:

{
  "api_key": "<SONIOX_API_KEY|SONIOX_TEMPORARY_API_KEY>",
  "model": "tts-rt-v1",
  "language": "en",
  "voice": "Adrian",
  "audio_format": "wav",
  "stream_id": "stream-001",
  "client_reference_id": "user_8f2c4b1a"
}

Text-to-Speech REST

Set in the body of POST /tts:

{
  "model": "tts-rt-v1",
  "language": "en",
  "voice": "Adrian",
  "audio_format": "wav",
  "text": "Hello from Soniox.",
  "client_reference_id": "user_8f2c4b1a"
}

Binding `client_reference_id` to a temporary API key

A client_reference_id can also be bound to a temporary API key at creation time. Every request authenticated with that key is logged with that identifier - no per-request field required from the client.

{
  "usage_type": "transcribe_websocket",
  "expires_in_seconds": 60,
  "client_reference_id": "user_8f2c4b1a"
}

For temporary API keys, client_reference_id must be set at creation time - it cannot be set or overridden later via the request. If no client_reference_id was bound when the key was created, log entries for requests using that key will have no client_reference_id, even if one is passed in the request.

Accessing logs

Fetch entries with GET /v1/usage-logs.

On this page