Sessions vs one-shot
When to mint a session and when to call a one-shot endpoint directly.
Speko supports two integration shapes. Pick based on whether your call is real-time interactive or single-turn batch.
One-shot endpoints
POST /v1/transcribe, POST /v1/synthesize, POST /v1/complete. Each is a single round-trip:
- Caller sends input + intent.
- Speko picks a provider, runs the call (with failover), returns the result.
Use for:
- Batch transcription of recorded audio.
- Server-side TTS for notifications, IVR prompts, exports.
- LLM completions in a non-voice flow.
No state is held between calls. There is nothing to clean up.
Real-time sessions
POST /v1/sessions creates one of two different media paths. Set mode explicitly so your client knows which response shape to expect.
Provider-direct S2S
mode: "s2s" reserves a bounded Speko entitlement and returns a scoped, short-lived credential for OpenAI Realtime, Gemini Live, or xAI Grok Voice. The browser passes that response to RealtimeVoiceConversation and connects directly to the selected provider.
The response has transport: "provider_direct", providerTransport, endpoint, credential, telemetry, and reservation fields. It does not contain LiveKit credentials:
your backend ── create session ──▶ Speko control plane
│
└── scoped credential + entitlement
│
browser ───────────── WebRTC / WebSocket ───────────▶ providerOpenAI uses WebRTC. Gemini Live and xAI use provider WebSockets. Speko stores content-free lifecycle and billing evidence. The OpenAI sideband observes provider control events but never receives media.
For S2S, ttlSeconds requests the maximum session horizon (default 1,800s, max 3,600s). The returned reservation.authorizedDurationSeconds may be lower because provider credentials can have shorter lifetimes. Gemini returns renewable slices; the browser client renews and resumes them while the requested horizon and credit authorization permit it.
Idempotency-Key is required. Reuse it after an ambiguous bootstrap timeout to recover the same reservation without minting a duplicate credential.
See Provider-direct speech-to-speech for a complete browser integration.
Cascade
mode: "cascade" returns a transportToken, transportUrl, and room name. The browser uses VoiceConversation to join LiveKit; Speko dispatches an agent worker into the same room to run the routed STT → LLM → TTS pipeline.
Two separate time controls apply to cascade sessions:
ttlSeconds(default 900s, max 86400s) bounds the join token only. It does not limit an already-connected session.maxDurationSeconds(default 3600s, min 30s, max 14400s) is the hard cap on session lifetime, measured from session creation. Speko force-ends the LiveKit room at the deadline. A call hosted on a speech-to-speech model (runMode: "s2s", e.g. GPT-Live) is capped at 3600s regardless of the requested value.
The agent worker leaves when the room empties or the max-duration deadline hits. The session row is retained for usage and audit.
Ending a session
For a cascade session, POST /v1/calls/{sessionId}/end tears down the LiveKit room and runs the normal close and metering flow. It is idempotent; ending an already-ended session returns status: "already_ended". SDK: client.sessions.end(sessionId) or client.calls.end(sessionId).
For provider-direct S2S, call RealtimeVoiceConversation.endSession() (or close the low-level realtime handle) to close the provider connection. The credential and entitlement stay time-bounded even if the client disappears without a final telemetry event.
Why a session ended
GET /v1/sessions/{id} and each GET /v1/sessions entry carry endReason, a string naming why the session closed. It is null while the session is live. Sessions closed from 2026-10-21 have one, including a plain hangup. It can still read null on a session that closed earlier on a plain hangup, and on a Pipecat-runtime session that completed normally.
A call can be ended by more than one thing at once: the callee hangs up as the max-duration cutoff fires, or the agent says goodbye while a voicemail is confirmed. The session keeps the most specific cause, whichever was reported first. From least to most specific: a hangup by the other party, then ended_by_api, then agent_ended, then the voicemail and timeout reasons, then a call that never connected or failed. So max_duration replaces callee_hangup and agent_ended, but nothing replaces sip_no_answer, and a failed session keeps its failure.
Sessions with status: "ended" closed normally:
endReason | Meaning |
|---|---|
callee_hangup | The person you called hung up, and nothing on Speko's side ended the call |
caller_hangup | The person who called in hung up, and nothing on Speko's side ended the call |
client_disconnected | A browser or SDK session: the client left, and nothing on Speko's side ended the session |
agent_ended | The agent hung up with the end_call tool |
voicemail_reached | A voicemail greeting answered and the voicemail policy ended the call |
machine_unavailable | The mailbox was full or not set up |
normal_timeout | Idle re-prompts ran out, a phone menu kept looping, or the other side kept repeating the same line |
dead_air | Nobody spoke for the silence window, or a mailbox, phone menu or call screener used up its time without taking input, so Speko hung up |
hold_timeout | Speko hung up while waiting on hold: the line was dead (no speech and no sound, hold music included) for 600 seconds, or turnHandling.holdTimeoutSeconds passed with nobody saying anything conversational, music or not. A queue that keeps playing music runs until maxDurationSeconds instead |
far_end_recording_loop | The outbound call was answered by a recording playing on a loop, and the agent was replying to it, so Speko hung up |
human_answered | A live person answered an outbound call with turnHandling.onHuman: "hangup", so Speko hung up without the agent saying anything |
max_duration | The session reached maxDurationSeconds |
ended_by_api | You ended the session with POST /v1/calls/{id}/end or POST /v1/sessions/{id}/end. An agent hangup, a voicemail verdict, a max-duration cutoff or a failure keeps its own reason |
sip_no_answer | The outbound call rang out unanswered |
caller_abandoned | The inbound caller hung up while the call was still ringing |
stale_timeout | The session stopped reporting and was closed by cleanup |
Sessions with status: "failed" carry the failure cause:
endReason | Meaning |
|---|---|
sip_busy | The outbound call was refused because the line was busy (SIP 486, 600) |
sip_declined | The callee or their carrier declined the call (SIP 603, 607) |
sip_invalid_number | The dialed number doesn't exist or is no longer in service (SIP 404, 410, 484, 604) |
sip_carrier_rejected | A carrier on the route refused the call: blocked, unauthorised, or a carrier error (other 4xx, 5xx, 6xx) |
sip_dial_rejected | The outbound call was refused before it rang, and the carrier gave no more specific reason |
originate_failed | The outbound call could not be placed |
no_agent_assigned, config_rejected | An inbound call had no usable agent configuration |
silent_bot_no_agent_audio | The agent never produced audio |
caller_not_connected | A browser session where nobody else was in the room when the agent was due to speak: the client never joined, or had already left |
stt_stream_lost, llm_empty_completion, tts_empty_audio | A speech-to-text, LLM, or text-to-speech stage failed |
provider_failed, credits_exhausted | A provider errored, or the workspace ran out of credits |
worker_crash, worker_joined_late, agent_dispatch_failed, agent_never_joined, worker_response_timeout, key_vend_failed, machine_action_failed | The agent worker failed |
unknown | A failure with no more specific cause, including a session that closed failed with none recorded |
On calls from a Speko number, LiveKit usually reports the refusal before the carrier's SIP code arrives. The sip.dial_rejected call-status webhook can therefore carry sip_dial_rejected while the session's endReason becomes a specific reason a moment later. Read endReason from GET /v1/sessions/{id} after the call ends; the call.hangup webhook that follows carries the SIP code.
Treat endReason as an open set: new values can appear, so handle an unrecognized string as "other".
Pinning an agent version
POST /v1/sessions and POST /v1/sessions/phone accept agentVersion, a version number from GET /v1/agents/{id}/versions. The session runs that version's saved config and workflow graph instead of the live one, and archived versions are allowed. Settings that versions do not record (tools, knowledge bases, webhooks) use their current values. It requires agentId, cannot be combined with useDraft, and an unknown number returns 404 AGENT_VERSION_NOT_FOUND.
Listing sessions
GET /v1/sessions returns sessions newest first. Pass nextCursor back as cursor to read the next page; sessions created in the same instant are never skipped between pages. Filters combine with AND: status, outcome, kind, agent, from and to (creation time), phone, phoneNumberId, minDuration and maxDuration, q with qScope, and gate.
To find sessions by your own IDs, filter on the metadata you sent at creation with metadata[key]=value:
curl --globoff "https://api.speko.dev/v1/sessions?metadata[leadId]=lead_456&metadata[campaign]=spring" \
-H "Authorization: Bearer $SPEKO_API_KEY"Every pair must match exactly, as a string, so a stored number or boolean does not match. Up to 10 keys are allowed. On a large workspace, add from and to to keep the search fast.
What happened on the call
GET /v1/sessions/{id} also carries what was recorded on the line, for every session, including dials nobody answered and dials the carrier refused:
| Field | Meaning |
|---|---|
answered, answeredAt | The carrier or the SIP leg recorded an answer, and when. Browser sessions have no phone leg and read false |
ringDurationMs | How long an outbound call rang before it was answered |
sipCode | The far end's final SIP response on a dial that never connected (486 busy, 603 declined, 404 no such number). null once the call was answered |
agentVersion | The agent version the session ran |
languageSwitches | Mid-call language changes: { atMs, from, to, method } |
dtmf | Every keypad key pressed on the call: { actor, key, atMs }, where actor is agent (the agent's send_dtmf) or callee (the far end). Callee keys are recorded only when the agent sets turnHandling.recordCallerKeypad: true; by default dtmf lists only the agent's own keys |
speechDetected, speechDetectedReason | Whether the caller said anything that reached the transcript. When false, the reason is silence (nothing was heard), not_recognized (speech was heard but produced no transcript) or stt_error (the transcription stream failed). true as soon as the caller says something; false only after the session ends. null while the session is open with nothing heard yet, and on a dialed call nobody answered |
voicemail | Machine detection: detected, amdVerdict, delivery, amdConfidence and amdDecidedAtMs (milliseconds from the answer to the verdict). amdConfidence is the confidence of the far-end reading that set the verdict; a verdict from the machine detector's own label carries no score, so it reads null |
report | The stored post-call report, the same object GET /v1/calls/{id}/report returns (snake_case). null until the report is finalized |
Every atMs counts milliseconds from the session's createdAt. The call.report webhook carries the same facts in snake_case; see Call facts on the report.
Marking test calls
Monitoring counts real calls only. If you place test calls through the API, set "test": true in the session metadata when you create them, and they stay out of Monitoring. Calls from Evaluation and from the dashboard's test buttons are left out already. To take out a call that has already happened, open it in Monitoring and choose Mark as test call.
Phone sessions
POST /v1/sessions/phone creates the same kind of voice session, then dials a PSTN destination over LiveKit SIP. Inbound calls follow the reverse path: a registered phone number receives the carrier webhook, Speko creates the voice session, hydrates the linked agent or dispatch metadata template, and bridges the caller into the room.
Use phone sessions for:
- Outbound appointment reminders, sales calls, and scheduled callbacks.
- Inbound receptionists and support lines.
- Calls that need carrier lifecycle events, forwarded-number metadata, post-call reports, recordings, or live transfers.
See Build a phone agent for the end-to-end phone flow.
Choosing
| Need | Use |
|---|---|
| Transcribe a file, return text | /v1/transcribe |
| Formatted transcript with diarization | /v1/transcribe + workload: transcription (guide) |
| Generate audio for a notification | /v1/synthesize |
| Long-form narration audio | /v1/synthesize + workload: narration (guide) |
| Single LLM reply, no voice | /v1/complete |
| Lowest-latency provider-native voice in a browser | /v1/sessions with mode: "s2s" + RealtimeVoiceConversation |
| Routed STT → LLM → TTS voice agent in a browser | /v1/sessions with mode: "cascade" + VoiceConversation |
| Outbound PSTN voice call | /v1/sessions/phone or speko.voice.dial() |
| Inbound PSTN receptionist | /v1/phone-numbers linked to an agent |
| Inspect reports, events, recordings, or transfers | /v1/calls/{id} |
| Real-time voice in a self-hosted framework worker | @spekoai/adapter-livekit directly, when using LiveKit |
What sessions don't do
- They aren't a chat history store. Cascade turn context lives in the worker; provider-direct context lives on the provider connection.
- They don't proxy audio through the REST API. S2S audio goes directly to the provider; cascade audio uses the LiveKit media transport.
- Provider-direct S2S reserves and settles a bounded duration entitlement. Cascade usage is recorded from its connected lifetime and underlying routed stages.
Recording
Cascade and phone sessions are recorded by default. The agent worker captures both speakers — caller and agent — into a single mixed-mono Opus file, persisted to Google Cloud Storage at the end of the call. There is no separate "enable recording" call for those modes.
Provider-direct S2S sessions are not recorded by Speko because their media never enters a Speko or LiveKit data path. Their recordingStatus is null, and GET /v1/sessions/{id}/recording has no artifact to return.
What gets captured:
- Mixed mono Opus. Both sides of the conversation in one file, ~24 kbps. Stereo / per-speaker tracks are not produced — assume one combined audio stream per session.
- The full call. Recording starts when the first participant joins the room and ends when the room empties (participants leave, the session is ended via the API, or the max-duration deadline hits).
- Audio only. Tool-call payloads and transcripts are not in the audio file; those live on the session row and the per-turn entries.
How to fetch one:
curl -L \
-H "Authorization: Bearer $SPEKO_API_KEY" \
https://api.speko.dev/v1/sessions/$SESSION_ID/recording \
--output session.opusThe endpoint 302-redirects to a short-lived (5 minute) signed GCS URL — pass -L so curl follows it. The signed URL is single-use within its TTL window; refetch the endpoint to get a fresh one rather than caching the URL itself.
The status field
Each session entry carries a recordingStatus that walks through:
pending— the call ended; the agent worker is assembling the file.uploading— the file is being pushed to GCS.ready— fully persisted and downloadable.recordingObjectPathandrecordingDurationMsare populated.failed— the upload errored. The recording is unrecoverable; the session itself is unaffected.suppressed— the organization hasrecordingEnabledset to false, so no file was ever produced. This is the terminal state for opted-out orgs; it's not a transient one.discarded— the call never connected (the session'sendReasonis one of the refused-dial reasons above (sip_busy,sip_declined,sip_invalid_number,sip_carrier_rejected,sip_dial_rejected) orsip_no_answer, orcaller_abandonedwhen the inbound leg was still ringing), or the recorder never received audio in a session where nobody spoke, so the capture held only an empty room. The file is withheld andGET /v1/sessions/{id}/recordingreturns 404; there was no conversation to play back.
null on recordingStatus appears on provider-direct S2S sessions and legacy entries that predate recording. Treat it as "not available" and don't expect a download.
Retention
Recordings are kept for 30 days after the session ends, then deleted automatically by a GCS lifecycle policy. There is no in-product way to extend retention — if you need long-term storage, download the file from the signed URL and store it in your own bucket. If you need shorter retention, see the per-org opt-out below.
Per-org opt-out
Recording is governed at the organization level by organization.recordingEnabled (default true). Flipping it to false:
- Stops new sessions from producing files. Their
recordingStatusbecomessuppressedandGET /v1/sessions/{id}/recordingreturns 404. - Does not retroactively delete prior recordings — those expire on the normal 30-day timer.
The flag is exposed in the dashboard under the Record voice sessions toggle on the Settings page.
An agent test call (POST /v1/agents/{id}/test-call) also accepts record: false. That test call's session is then suppressed even when the org default is on. record: true never turns recording on for an org that has it off.
API endpoint
GET /v1/sessions/{id}/recording is the only supported way to retrieve a recording. It authenticates with the same bearer key as every other endpoint and returns 200 with a JSON body { "url": "...", "expiresAt": "..." } on success. The url is a signed download link valid for 5 minutes and expiresAt is when it stops working, so fetch it right away and call the endpoint again for a fresh one. It returns 404 when the session is unknown, the recording is not ready, failed, suppressed, or absent for provider-direct S2S. Inspect the parent session entry's recordingStatus to disambiguate. Never construct GCS URLs from recordingObjectPath directly — those URLs are not publicly addressable, and the field exists only as an internal handle.
Post-call analysis
In Settings → Workspace → Post-call analysis, an owner or admin can turn off post-call analysis for the workspace. The Settings overview links directly to this control and shows its current state.
organization.postCallAnalysisEnabled defaults to true for new and existing
workspaces. GET /v1/organization returns the current value. An owner or admin
user can update it with PATCH /v1/organization and a boolean body:
{ "postCallAnalysisEnabled": false }Members and API keys cannot change this policy. Recording and deploy blocking have independent switches; updating analysis alone does not change either one.
When disabled, Speko stops submitting transcripts to OpenAI for post-call analysis, including forced/manual retries and monitoring re-scoring. It records no new post-call analysis usage. Calls still complete, transcripts are retained, and reports and webhooks continue with a heuristic fallback. Existing completed analysis and reports are preserved, including on forced retries. This setting does not change the live call's STT, LLM, or TTS pipeline, and it does not delete historical data or recall analysis already in flight. Re-enabling restores future analysis; it does not automatically re-analyze historical calls.
Monitoring records intentionally skipped analysis as unavailable, rather than an analysis failure. Unavailable analysis scores do not enter success/pass-rate metrics or trigger analysis-based alerts. Deterministic pipeline, transport, dead-air and latency checks still run, and existing completed analysis keeps its legitimate scores.
Transcript
Every finalized STT and LLM turn during a cascade session is persisted server-side. The dashboard's session detail page surfaces them under a Transcript card; the API equivalent is GET /v1/sessions/{id}/transcript, which returns turns sorted by index.
The worker batches and debounces (~200ms) finalized turns and POSTs them to /v1/sessions/{id}/turns. The ingest endpoint is idempotent on (session_id, index) so retries on transient errors are safe.
Interim STT partials are not persisted — only finalized turns make it into the transcript.
Provider-direct S2S transcripts are available to the connected client through provider events, but Speko does not currently persist them. GET /v1/sessions/{id}/transcript therefore returns no S2S turns.