Execution payload reference

An execution is the record of one call. The same payload is returned by Get execution, pushed to your webhook, listed by Get agent executions, and shown as Raw Call Data in Call History. It carries the call record, the billing record and the diagnostic record in one object. Most integrations need a dozen of its keys. This page groups them by what they are for.

List endpoints return a trimmed projection: id, status, conversation_duration, created_at and a short telephony_data. Fetch the execution by id, or receive it on a webhook, to get everything below. A payload can also contain keys that are not listed here; those are internal and carry no compatibility guarantee, so do not build on them.

Before you build on this

Three things account for most of the bugs people hit reading this payload.

Nothing is final until the status is terminal

conversation_duration, total_cost, telephony_data.recording_url, transcript and extracted_data are null, 0 or empty until the call finishes and post-processing runs. Read them earlier and you will record zeros. See the status lifecycle.

`status: "completed"` does not mean a conversation happened

status is derived from the telephony provider’s call-lifecycle field, not from the hangup cause, so a call the callee rejected can still arrive as completed. Check conversation_duration > 0 before treating a call as answered. telephony_data.hangup_reason and hangup_provider_code carry the real ending.

A webhook fires several times for one call

Bolna POSTs this payload as the call’s status changes, so a single call produces multiple deliveries carrying the same id. Make your handler idempotent and key it on id, or you will count the same call more than once. Together those three give the shape of a correct handler: ignore non-terminal deliveries, then decide what actually happened before recording anything.

Handling a delivery

TERMINAL = {"completed", "no-answer", "busy", "failed",
            "canceled", "stopped", "error", "balance-low"}

def handle(execution):
    if execution["status"] not in TERMINAL:
        return                                  # more deliveries are coming for this call

    telephony = execution["telephony_data"]

    # `completed` on its own is not enough; check that a conversation actually took place
    if execution["conversation_duration"] == 0:
        return record_no_conversation(
            execution["id"], telephony["hangup_reason"], telephony["hangup_provider_code"]
        )

    # the transcript is how you tell whether the caller ever spoke
    transcript = execution.get("transcript") or ""
    if not any(line.startswith("user:") for line in transcript.splitlines()):
        return record_agent_only(execution["id"])   # agent spoke, caller never did

    record_conversation(execution["id"], transcript, execution["extracted_data"])

handle is keyed on execution["id"], so a repeated delivery for the same call overwrites rather than duplicates. That is what makes it safe against point 3.

A complete payload

A real completed call. The agent’s welcome message played, the caller never spoke, and the agent hung up after its silence timeout.

Completed execution

{
  "id": "b7140255-af33-4608-8e97-04dd944b8e48",
  "agent_id": "5bc97541-e320-4d95-a3a5-242cfe45621d",
  "batch_id": null,
  "campaign_id": null,

  "status": "completed",
  "smart_status": null,
  "error_message": null,
  "conversation_duration": 28,
  "answered_by_voice_mail": null,

  "created_at": "2026-09-04T08:52:07.408883+00:00",
  "initiated_at": "2026-09-04T08:52:09.737874",
  "updated_at": "2026-09-04T08:52:59.320486+00:00",
  "scheduled_at": null,
  "rescheduled_at": null,

  "user_number": "+919876543210",
  "agent_number": "+918035739222",
  "provider": "vobiz",

  "transcript": "assistant: Hello, this is Sonam from Bolna's Community...\nassistant: Hello, are you still on the line?\n",
  "summary": null,
  "extracted_data": {},

  "telephony_data": {
    "duration": 28,
    "to_number": "+919876543210",
    "from_number": "+918035739222",
    "recording_url": "https://api.bolna.ai/recordings/call/b7140255-af33-4608-8e97-04dd944b8e48",
    "hosted_telephony": true,
    "provider_call_id": "a41e7c93-2b58-4e07-95d1-8f30c62b7a11",
    "call_type": "outbound",
    "provider": "vobiz",
    "hangup_by": "Caller",
    "hangup_reason": "inactivity_timeout",
    "hangup_provider_code": 4010,
    "ring_duration": null,
    "post_dial_delay": null,
    "to_number_carrier": null
  },

  "total_cost": 3,
  "cost_breakdown": {
    "platform": 1,
    "network": 0.25,
    "transcriber": 0.432,
    "synthesizer": 0.69,
    "llm": 0,
    "total_cost_to_deduct": 1.878,
    "llm_breakdown": { "conversation": 0, "extraction": 0, "summarization": 0, "hangup": 0, "routing": 0, "analytics": 0, "voicemail": 0 },
    "synthesizer_breakdown": { "conversation": 0.69, "welcome_message": 0 },
    "transcriber_breakdown": { "conversation": 0.432, "analytics": 0 },
    "transfer_cost": 0
  },

  "usage_breakdown": {
    "transcriber_provider": "deepgram",
    "transcriber_model": "nova-3",
    "transcriber_language": "en",
    "transcriber_duration": 28.199938,
    "synthesizer_provider": "elevenlabs",
    "synthesizer_model": "eleven_turbo_v2_5",
    "synthesizer_characters": 217,
    "voice_id": "IkSv4tkouLJ6kYsQA7XD",
    "llmTokens": 0,
    "llmModel": { "azure/gpt-4.1-mini": { "input": 0, "output": 0 } },
    "provider_source": { "llm": "bolna", "synthesizer": "bolna", "transcriber": "bolna" },
    "llm_usage_breakdown": {
      "conversation": { "model": "azure/gpt-4.1-mini", "provider": "azure", "input": 0, "output": 0 },
      "disposition": { "model": null, "input": 0, "output": 0, "cached_tokens": 0 }
    },
    "synthesizer_usage_breakdown": { "conversation_characters": 69, "welcome_message_characters": 148, "welcome_message_cache": false, "provider_connected": false },
    "transcriber_usage_breakdown": { "transcriber_duration": 28.199938, "provider_connected": false },
    "endpointing": 200,
    "incremental_delay": 300,
    "buffer_size": 220,
    "hangup_after_silence": 15,
    "check_if_user_online": true,
    "trigger_user_online_message_after": 10,
    "voicemail_detection_enabled": false
  },

  "latency_data": {
    "time_to_first_audio": 262.37671,
    "stream_id": 257.49268,
    "region": "in",
    "transcriber": { "time_to_connect": 17, "turns": [] },
    "llm": { "time_to_connect": null, "turns": [] },
    "synthesizer": { "time_to_connect": 88, "turns": [{ "turn": -1, "time_to_first_token": 110, "time_to_last_token": 311 }] },
    "rag": null,
    "interruption_stats": {
      "total_interruptions": 0,
      "user_interrupted_agent_count": 0,
      "agent_interrupted_user_count": 0,
      "user_speaking_ms": 0,
      "agent_speaking_ms": 0,
      "longest_agent_monologue_ms": 0,
      "talk_to_listen_ratio": null,
      "barge_in_recovery_rate": null,
      "barge_in_recovery_count": 0
    }
  },

  "tool_call_logs": [],
  "transfer_call_data": null,
  "context_details": {
    "recipient_phone_number": "+919876543210",
    "recipient_data": { "timezone": "Asia/Kolkata" }
  },
  "retry_count": 0,
  "retry_config": null,
  "retry_history": null
}

Identity and linkage

Field	Type	Notes
`id`	uuid	The execution id. Use it with Get execution and raw logs.
`agent_id`	uuid	Agent that ran the call
`batch_id`	uuid \| null	Set for batch calls
`campaign_id`	uuid \| null	Set for workflow campaign calls

Status and lifecycle

Field	Type	Notes
`status`	string	The status you should branch on. See the full lifecycle, and the warning above about `completed`.
`smart_status`	string \| null	An outcome read from the transcript by a model. `null` for zero-duration calls, so treat it as a hint on top of `status`, never a replacement.
`error_message`	string \| null	Populated on `error` and some `failed` calls
`conversation_duration`	number	Conversation seconds. `0` means no conversation took place, whatever `status` says.
`answered_by_voice_mail`	boolean \| null	Set when voicemail detection is enabled and fires

Timing

Field	Type	Notes
`created_at`	timestamp	When the execution record was created
`initiated_at`	timestamp	When dialling actually started
`updated_at`	timestamp	Last write, normally the end of post-processing
`scheduled_at`	timestamp \| null	For scheduled calls
`rescheduled_at`	timestamp \| null	Set when the call was rescheduled

created_at and initiated_at differ by the queue wait. Use initiated_at when measuring dial-to-answer behaviour, and created_at when reconciling against the moment you made the request. Scheduled calls also use the statuses scheduled and rescheduled, which sit before queued.

Conversation content

Field	Type	Notes
`transcript`	string	Newline-delimited `speaker: text`. Speakers are `assistant` and `user`. This is how you tell whether the caller ever spoke.
`summary`	string \| null	Populated only when the agent’s `call_summary_enabled` toggle is on. Off by default.
`extracted_data`	object	Post-call extractions, nested `Category` then `Extraction` then `{ subjective, objective, confidence, confidence_label, reasoning_subjective, reasoning_objective, validation }`. `{}` when the agent has no dispositions.

Telephony

All under telephony_data.

Field	Type	Notes
`duration`	number	Call duration in seconds as reported by the provider. Compare with the top-level `conversation_duration`, which is the figure billing uses.
`to_number` / `from_number`	string	Also mirrored at the top level as `user_number` / `agent_number`
`recording_url`	string \| null	`null` if recording is off or the call never connected
`call_type`	string	`outbound` or `inbound`
`provider`	string	`twilio`, `plivo`, `exotel`, `vobiz`, `sip-trunk`
`hosted_telephony`	boolean	Whether the number is Bolna-hosted rather than your own
`provider_call_id`	string	The provider’s id for the call. Quote this in a provider support ticket.
`hangup_by`	string	Which side ended the call, for example `Caller`, or the provider name when the platform ended it
`hangup_reason`	string	Normalised reason, for example `inactivity_timeout`
`hangup_provider_code`	integer \| null	The provider’s raw code. Carries rejection detail that `status` can miss. See the warning above.
`ring_duration`	number \| null	Seconds spent ringing, when the provider reports it
`post_dial_delay`	number \| null	Dial to first ring, when the provider reports it
`to_number_carrier`	string \| null	Carrier lookup for the dialled number, when available

Cost

total_cost and cost_breakdown are the billing figures, reported in cents. The dashboard presents the same numbers as credits. See Call pricing.

Field	Notes
`total_cost`	Total for the call
`cost_breakdown.platform` / `network`	Bolna platform fee and telephony
`cost_breakdown.transcriber` / `synthesizer` / `llm`	Per-component cost
`cost_breakdown.total_cost_to_deduct`	The wallet deduction for this call. It can differ from `total_cost`, so reconcile billing against this field.
`cost_breakdown.llm_breakdown`	LLM cost split by purpose: `conversation`, `extraction`, `summarization`, `hangup`, `routing`, `analytics`, `voicemail`. A call with extractions bills more than one LLM pass.
`cost_breakdown.synthesizer_breakdown`	Splits `conversation` from `welcome_message`, which is cached separately
`cost_breakdown.transcriber_breakdown`	Splits `conversation` from `analytics`
`cost_breakdown.transfer_cost`	Added when the call was transferred

Usage

usage_breakdown is the unit-level detail behind the cost. Read it when you want to know why a call cost what it did, or which models actually ran.

Field	Notes
`transcriber_provider` / `transcriber_model` / `transcriber_language`	The transcriber that ran
`transcriber_duration`	Seconds of audio transcribed, fractional
`synthesizer_provider` / `synthesizer_model` / `voice_id`	The voice that ran
`synthesizer_characters`	Characters synthesised
`llmModel` / `llmTokens`	Model used and total tokens
`llm_usage_breakdown`	Per-purpose token detail for `conversation`, `disposition`, `extraction` and `summarization`, each with `input` and `output`
`provider_source`	Whether each component billed to `bolna` or to your own connected key
`synthesizer_usage_breakdown`	Splits `conversation_characters` from `welcome_message_characters`, and reports whether the welcome message was served from cache
`transcriber_usage_breakdown`	Transcribed duration, and whether your own key served the call
`endpointing`, `incremental_delay`, `buffer_size`, `hangup_after_silence`	The latency-relevant settings this call ran with. Useful when comparing two calls that behaved differently.
`check_if_user_online`, `trigger_user_online_message_after`, `voicemail_detection_enabled`	The presence-detection settings this call ran with

Latency

latency_data is the diagnostic record. See Call latencies for how to read it.

Field	Notes
`time_to_first_audio`	Milliseconds from the end of the caller’s utterance to the start of the agent’s audio. The number callers actually feel.
`region`	Region the media ran in
`transcriber` / `llm` / `synthesizer`	Each has `time_to_connect` and a `turns` array of per-turn timings
`interruption_stats`	Barge-in behaviour: counts in each direction, speaking time each side, `longest_agent_monologue_ms`, `talk_to_listen_ratio` and barge-in recovery. The first place to look when an agent talks over people.
`rag`	Knowledge-base retrieval timings, when the agent uses one
`routing`	Semantic-routing timings, when the agent uses routes

If PII masking is enabled on your account, phone numbers, telephony_data.recording_url and the string values inside extracted_data come back as null. The keys are still present, so code that reads them sees null rather than a missing field. Check with your account settings before building on those values.

Transfers, context and retries

Field	Notes
`tool_call_logs`	Always returned as an empty array. Per-invocation function tool detail is not included in API responses; read it from the execution in the dashboard instead.
`transfer_call_data`	Populated when the call was transferred
`context_details`	The recipient context the call ran with, including `recipient_phone_number` and any `recipient_data` variables you passed
`agent_context_details`	Agent-side context, when set
`batch_run_details`	Batch row detail for batch calls
`retry_count`	Attempts so far
`retry_config`	The auto-retry policy in force
`retry_history`	Prior attempts
`workflow_retries`	Retries driven by a workflow

Reading the payload well

Did a real conversation happen?

Check conversation_duration > 0, then look for a line starting with user: in transcript. status alone is not enough, because it comes from the telephony provider’s lifecycle field and can read completed for a call the callee rejected. telephony_data.hangup_reason and hangup_provider_code tell you how it really ended.

Why did this call cost what it did?

Start at cost_breakdown.llm_breakdown, because extractions and summarisation are separate LLM passes on top of the conversation, so an agent with many dispositions costs more per call. Then check usage_breakdown.provider_source: components billing to bolna are charged to your wallet, while ones billing to your own connected key are not.

Why was the agent slow?

latency_data.time_to_first_audio is what the caller felt. Split it with the per-component time_to_connect and turns values to see which leg was slow, then compare usage_breakdown.endpointing and incremental_delay against a call that felt fine. See Call latencies.

Why did the agent talk over the caller?

latency_data.interruption_stats, specifically agent_interrupted_user_count, longest_agent_monologue_ms and barge_in_recovery_rate. The settings that change this behaviour, interruption thresholds and endpointing, live in the Engine tab.

Can I get this pushed to me instead of polling?

Yes. Set webhook_url on the agent and Bolna POSTs this same payload as the call progresses. Whitelist 13.203.39.153, 13.126.9.249 and 13.202.133.53. See Webhooks.

Overview

Agents

Calls

Executions

Tasks

Batches

Workflows

Workflow Campaigns

Workflow Executions

Inbound

Phone Numbers

Knowledgebases

Dispositions

Extraction Categories

Providers

Sub-Accounts

Voice

User

SIP Trunks (BYOT)

Violations

Legacy APIs

Execution payload reference

Before you build on this

Nothing is final until the status is terminal

`status: "completed"` does not mean a conversation happened

A webhook fires several times for one call

A complete payload

Identity and linkage

Status and lifecycle

Timing

Conversation content

Telephony

Cost

Usage

Latency

Transfers, context and retries

Reading the payload well

​Before you build on this

​Nothing is final until the status is terminal

​status: "completed" does not mean a conversation happened

​A webhook fires several times for one call

​A complete payload

​Identity and linkage

​Status and lifecycle

​Timing

​Conversation content

​Telephony

​Cost

​Usage

​Latency

​Transfers, context and retries

​Reading the payload well

Before you build on this

Nothing is final until the status is terminal

`status: "completed"` does not mean a conversation happened

A webhook fires several times for one call

A complete payload

Identity and linkage

Status and lifecycle

Timing

Conversation content

Telephony

Cost

Usage

Latency

Transfers, context and retries

Reading the payload well