Sign in

v1

latestOpenAPI 3.1.02026-07-22152755.8 KB
Observability

Ingest a production call (webhook)

Primary ingestion endpoint for production call logs. Your agent (or its provider's post-call webhook) POSTs here with the transcript, recording URL, and metadata; Cekura stores it as a CallLog, schedules metric evaluation, and surfaces it in Observability.

Identifying the agent (pick one):

  • agent — Cekura agent ID (preferred when you've already registered via POST /aiagents/)
  • assistant_id — external assistant identifier (VAPI/Retell/OpenAI-style asst_...). Cekura resolves it to your agent.

Transcript formats (via transcript_type):

  • vapi, retell, elevenlabs, bland, livekit, pipecat, koreai — provider-native shapes; pass transcript_json exactly as the provider emits it.
  • cekura (default) — [{role, content, start_time, end_time}, ...]. Valid roles: "Testing Agent" (the caller) and "Main Agent" (the agent under test). Note: "agent" and "user" are not valid for this format.

Provider-specific alternatives:

  • LiveKit webhooks: POST /observability/v1/livekit/observe/ (raw LiveKit webhook shape)
  • Pipecat webhooks: POST /observability/v1/pipecat/observe/ (raw Pipecat webhook shape)

Fields to know:

  • voice_recording_url — link to the call audio; enables audio-based metrics.
  • metadata — freeform tags for filtering in Observability (customer_id, campaign_id, etc.).
  • dynamic_variables — values injected into the agent at runtime; shown alongside the transcript.
  • customer_number — caller's number in E.164 format, e.g. +14155551234.
  • call_ended_reason — reason for call termination (completed, user-hangup, agent-hangup, etc.).
  • metric_ids — comma-separated metric IDs to evaluate immediately (e.g. "1,2,3").

Async processing: metrics are evaluated in the background. The initial response shows status: "evaluating" with an empty metrics list. Retrieve the call log again after 30–60 seconds to see completed metric results.

Billing: each ingested call consumes observability credits. Calls with audio cost more than text-only calls. Check your balance via GET /test_framework/v1/billing_info.

post/observability/v1/observe/

Request body

idinteger
call_idstring

Unique identifier for the call. Example:

  • "call_abc123xyz"
  • "stereo_audio_session_456"
trace_idstring

OpenTelemetry trace ID (32-char hex string). Example: "4bf92f3577b34da6a3ce929d0e0e4736"

agentinteger

Agent ID, required if assistant_id not provided Example: 2421

assistant_idstring nullable

Provider's Assistant ID, required if agent not provided Example:

  • "asst_abc123xyz"
  • "agent_xyz789"
voice_recordingstring uri nullable

Audio recording file of the call. Example: Binary data "recordings/call_123_20240315.mp3"

voice_recording_urlstring uri nullable

URL to call recording audio file Example: "https://storage.example.com/recordings/call_123.mp3"

transcript_type'cekura' | 'vocera' | 'vapi' | 'retell' | 'deepgram' | 'pipecat' | 'livekit' | 'elevenlabs' | 'none-mono'

Format of the transcript_json payload. Tells Cekura how to parse roles and timestamps.

  • vapi — Vapi webhook format: [{"role": "bot"|"user", "message": "...", "time": 0.0}]
  • retell — Retell webhook format
  • elevenlabs — ElevenLabs format
  • livekit — LiveKit format
  • pipecat — Pipecat format
  • deepgram — Deepgram format
  • cekura (default) — [{"role": "Testing Agent"|"Main Agent", "content": "...", "start_time": 0.0, "end_time": 2.5}]. Valid roles are "Testing Agent" and "Main Agent" only — using "agent" or "user" will return a validation error.
  • none-mono — mono audio with no transcript; Cekura generates the transcript automatically.

Omit this field to use the default Cekura format.

  • cekura - cekura
  • vocera - vocera
  • vapi - vapi
  • retell - retell
  • deepgram - deepgram
  • pipecat - pipecat
  • livekit - livekit
  • elevenlabs - elevenlabs
  • none-mono - none-mono
{"stackTrail":"components:schemas:CreateCallLog:properties:transcript_json","oasType":"schema","type":"unknown","description":"\nCall transcript in supported format (Vapi, Retell, Deepgram, ElevenLabs, Cekura)\n\nCheck the [Transcript Format](/documentation/advanced/transcript-format) documentation for more details.\n\nCekura Transcript Format Example:\n"}

Response

{"stackTrail":"components:schemas:CallLogList","oasType":"schema","type":"unknown","description":"Referenced by this API but not published in the vendor's docs pages."}
All 15 operations