Calls API: place and track AI phone calls

A call is one outbound dial attempt driven by an agent. Creating a call is asynchronous: you get 202 Accepted immediately and the outcome arrives by webhook (or by polling GET /v2/calls/{id}). To show the call while it runs, open its live event stream. A call can also run in your user’s browser instead of on a phone: create it with channel: "web". See Browser calls for the whole flow.

Environment	Base URL
Sandbox	`https://sandbox.voice.miraiminds.co`
Production	`https://prod.voice.miraiminds.co`, once your company has gone live

The examples on this page use the sandbox address. On the production address, a key from a workspace that has not gone live is refused with 403 production_workspace_required.

The call object

{
  "id": "call_01K7Q9B4M8N3P6R2S5T7V9W1YA",
  "object": "call",
  "agent_id": "agt_01K7Q9F3K7M2N5P9R4T6V8W0XZ",
  "to": "+919876543210",
  "channel": "phone",
  "status": "completed",
  "tier": "t3",
  "ended_reason": "customer-ended-call",
  "created_at": "2026-08-10T09:15:00Z",
  "started_at": "2026-08-10T09:15:02Z",
  "ended_at": "2026-08-10T09:16:38Z",
  "duration_secs": 96,
  "cost": {
    "amount_inr": 5,
    "per_min_inr": 3,
    "billing_block_secs": 10,
    "voice_per_min_inr": 3
  },
  "recording_available": true,
  "transcript_available": true,
  "transcript_status": "ready",
  "metadata": { "order_id": "8842" },
  "call_settings": {
    "voice_id": "neha",
    "language": "hi",
    "secondary_languages": ["en"],
    "sources": { "voice_id": "request", "language": "agent", "secondary_languages": "agent" }
  },
  "analysis": null
}

Field	Type	Description
`id`	string	`call_<ulid>`. Also the idempotency anchor and the workflow ID.
`agent_id`	string	The agent this call ran.
`to`	string	E.164 destination. On an incoming call, your number.
`from`	string	Phone calls only. The number the call rang from: your number or the shared line on a call you place, the caller’s number on an incoming call.
`direction`	string	`outbound` for a call you or a campaign placed, `inbound` for a call to one of your numbers.
`channel`	string	`phone`, `web` (a browser call), `text` (a typed test chat from the console) or `realtime`. Calls placed before this field existed read as `phone`.
`status`	enum	See statuses.
`tier`	string	The rate card this call was billed under, which is your company’s plan. See tiers.
`ended_reason`	string \| null	Why it ended. See ended reasons. `null` while running.
`created_at`	string	RFC 3339, UTC. When we accepted the request.
`started_at`	string \| null	RFC 3339, UTC. Set when media goes live, not when we dialled. `null` if the call never connected.
`ended_at`	string \| null	RFC 3339, UTC.
`duration_secs`	integer \| null	Billable seconds of live media. `0` for calls that never connected, `null` while running.
`cost.amount_inr`	number	Total rupees charged. `0` until the call is billed and for outcomes that are free.
`cost.per_min_inr`	number	The all-in per-minute rate this call is billed at.
`cost.billing_block_secs`	integer	The voice billing block in seconds: 10.
`cost.voice_per_min_inr`	number	Voice AI rate quoted for this call, when a pricing snapshot is available.
`cost.insights_per_min_inr`	number	T1 insights rate when enabled; absent when no insights charge applies.
`cost.telco_per_min_inr`	number	Managed provider rate; absent for BYO telco, WhatsApp and browser calls.
`cost.telco_provider`	string	The managed provider, when a provider charge applies.
`cost.telco_billing_block_secs`	integer	The provider’s billing block, which can differ from the voice AI block.
`cost_inr`	number \| null	The same total as `cost.amount_inr`, kept for older integrations. `null` until the call is billed and on free calls. Use `cost.amount_inr` in new code.
`recording_available`	boolean	Whether `GET /recording` will return audio.
`transcript_available`	boolean	Whether `GET /transcript` will return turns.
`transcript_status`	enum	`pending` while the call runs and until its transcript is stored; `ready` when `GET /transcript` returns turns; `empty` when nobody spoke; `failed` when the transcript could not be stored.
`metadata`	object	Your `metadata` from create, unchanged. For a campaign call, the contact’s `metadata`. Absent when the call has none.
`phone_number_id`	string	The phone number the call rang from, when it came from one of your own.
`pool_id`	string	The phone pool that picked the number. Only when a pool did, and then `calls_from_source` is `pool`.
`campaign_id`	string	The campaign that placed the call. Only on campaign calls.
`contact_id`	string	The campaign contact the call was to: the `id` you sent with the contact, or the one we minted. Only on campaign calls.
`call_settings`	object	The voice and languages the call runs with, and who chose each. See call settings. Absent on calls from before per-call settings existed (October 2026) and on incoming calls turned away before an agent was found.
`analysis`	object \| null	The post-call analysis when the agent has `analysis.enabled`: summary, `success`, extracted `data` and, with templates, the chosen follow-up message in `analysis.template`. `null` otherwise.

Flow outcome

A call run by a node-based agent also carries flow: where the flow finished, the steps it went through and the values it extracted. It appears here, on each call in GET /v2/calls, and at data.call.flow in call.processed. A call run by a single-prompt agent has no flow field.

{
  "flow": {
    "final_node": "goodbye",
    "nodes_visited": ["Confirm the customer", "Offer the delivery slot", "Close"],
    "variables": { "identity_confirmed": true, "slot_accepted": true },
    "status": "end_call",
    "tags": ["end_call"]
  }
}

Field	Description
`final_node`	The `id` of the node the call ended on. Omitted when unknown.
`nodes_visited`	The `name` of each node the call entered, in the order it first entered them. Always present; `[]` when none.
`variables`	Every extracted value, by variable name. Always present; `{}` when none.
`status`	How the flow ended: `end_call`, `user_hangup`, `user_idle_max_duration_exceeded`, `call_duration_exceeded`, `voicemail_detected`, `pipeline_error` or `system_cancelled`. Omitted when unknown. See reading the outcome.
`tags`	Labels recorded for the call, such as how it ended. Omitted when unknown.

flow is absent until the outcome is recorded, usually within seconds of the call ending, so it can be missing from the terminal event. call.processed waits up to 2 minutes for it.

Statuses

Status	Terminal	Meaning
`queued`		Accepted, waiting on fleet capacity. A browser call stays here until the page connects its audio.
`dialing`		SIP invite sent, phone is ringing. Phone calls only.
`in_progress`		Media live, conversation running.
`completed`	✅	Connected and finished normally. Billable.
`voicemail`	✅	An answering machine picked up. See voicemail. Billable.
`no_answer`	✅	Rang out, nobody picked up. Free.
`busy`	✅	Callee’s line was busy. Free.
`failed`	✅	Could not connect, or the pipeline errored. Free.
`timeout`	✅	Hit `max_duration_secs`. Billable.
`aborted`	✅	You cancelled it with `POST /abort` while it was queued, ringing or mid-conversation. Free in every case.

Statuses only move forward. A terminal status never changes.

Ended reasons

ended_reason explains why a terminal status was reached. Match on status for control flow; use ended_reason for analytics and support.

`ended_reason`	Usual `status`	Meaning
`assistant-ended-call`	`completed`	The agent called `end_call` because its job was done.
`customer-ended-call`	`completed`	The callee hung up.
`exceeded-max-duration`	`timeout`	Hit `max_duration_secs`.
`customer-did-not-answer`	`no_answer`	Rang out.
`customer-busy`	`busy`	Line busy.
`voicemail`	`voicemail`	An answering machine answered. Detecting the machine is what sets the status, so this reason and that status always appear together.
`silence-timed-out`	`completed`	Media was live but nobody ever spoke. Billable, because the agent ran.
`idle-timed-out`	`completed`	The caller went quiet. The agent checked in once after about 10 seconds, then said goodbye. Billable.
`no-media`	`failed`	The call was placed but its audio never arrived. An incoming caller who hung up before we answered, and a call to a number whose connection is switched off, also end this way. See the note below. Not billed.
`insufficient_balance`	`failed`	Your wallet couldn’t pay for the call when we set it up, so it never started. An incoming caller is not answered. It has an underscore, the same spelling as the `402 insufficient_balance` that `POST /v2/calls` answers with. Not billed.
`agent-unavailable`	`failed`	An incoming call that no agent could take. The number has no agent, or its agent is missing, a draft or archived, runs a flow your plan’s model can’t run, or needs an input an incoming call can’t supply. A WhatsApp number or integration that is switched off ends this way too. The caller is not answered. Not billed.
`setup-timeout`	`failed`	An incoming call we couldn’t get ready before the caller’s ring ran out. Not billed.
`skipped-by-condition`	`aborted`	A pre-call `skip_call` matched, or your WhatsApp resolver answered `allow: false`. Nothing was dialled, and an incoming caller is not answered. Free.
`precall-tool-failed`	`failed`	A pre-call tool with `on_failure: "abort"` failed or ran out of time. Nothing was dialled, and an incoming caller is not answered. Free.
`aborted-by-api`	`aborted`	You called `POST /abort`. An abort produces this reason and no other.
`api-ended-call`	`completed`	You sent a `close` control: the agent said goodbye and the call ended. Billable.
`time-limit-close`	`completed`	The timing policy closed the call before its hard cap. Billable.
`user-silence-close`	`completed`	The timing policy closed the call after the user stayed silent for `user_silence_close_secs`. Billable.
`assistant-error`	`failed`	A failure on our side, while setting the call up or during it. Not billed.
`transferred`	`completed`	Reserved for a call that ends in a warm transfer to a human. Transfer is not available yet, so no call emits this yet. See the roadmap.
`balance-exhausted`	`completed`	Reserved for a call ended when the wallet emptied mid-call. Not wired, so no call emits this yet.

Treat ended_reason as an open vocabulary. We add new values without a version bump, so always have a default branch. The last two rows above are in the vocabulary, but no call emits them today. They arrive when warm transfer and later releases ship. See the roadmap.

no_answer is under-reported todaySome calls that genuinely rang out are reported as failed with ended_reason: "no-media" rather than as no_answer.Whether we can tell the two apart depends on what the carrier tells us. When the carrier returns a clear verdict (SIP 480 or 408 for rang out, 486 or 600 for busy), you get no_answer or busy correctly. When it black-holes the call instead, accepting the invite and returning nothing, we have no signal to tell “rang, nobody picked up” apart from “answered into silence”. The call then ends as failed with no-media after the media gate expires.If you count unanswered calls for retry logic, treat no_answer, busy, and failed with no-media together as calls that did not connect. None of the three is billed, so your costs are unaffected either way. We are working on this, and the reported status will only get more specific over time.

Create a call

POST /v2/calls

Request

Field	Type	Required	Description
`agent_id`	string	yes	The agent to run.
`channel`	string	no	`phone` (default) or `web`. `web` runs the call in a browser. See Browser calls.
`to`	string	phone only	E.164, e.g. `+919876543210`. Required for phone calls. Refused with `400 invalid_request` on `channel: "web"`.
`variables`	object	no	Flat string map substituted into the agent’s prompt. See variables.
`metadata`	object	no	Your own identifiers, up to 16 string keys and values. Returned unchanged on the call and in every webhook. Never shown to the agent. See metadata.
`first_message`	string	no	The opening line for this call only, up to 500 characters. Replaces the agent’s `first_message`; `{{variable}}` placeholders work the same way. Refused for a node-based agent, whose start node opens the call.
`system_prompt`	string	no	The agent’s instructions for this call only, 1 to 16,000 characters. Replaces the agent’s `system_prompt`; `{{variable}}` placeholders are filled from `variables`. Refused on `channel: "realtime"` and for a node-based agent. Never returned on the call or in webhooks. See per-call prompt.
`call_settings`	object	no	The voice and languages for this call only: `voice_id`, `language` and `secondary_languages`. The agent is not changed. See call settings.
`webhook_url`	string	no	HTTPS URL for lifecycle events. Applies to this call only.
`phone_number_id` / `pool_id`	string	no	Phone calls only. Ring from one of your own phone numbers, or from the number a pool picks. Without either, the call uses the agent’s `calls_from`, then your default pool, then the Mirai shared line. Send one, not both.
`max_duration_secs`	integer	no	Overrides the agent’s cap for this call only.
`timing`	object	no	Wrap-up, timed-close and user-silence timers for this call. Phone and browser calls. See timing policy.
`recording_enabled`	boolean	no	Default `true`. `false` stores no audio for this call: no recording, `recording_available: false`. If your workspace has recording turned off, the default is `false` and `true` is refused with `403 recording_disabled`.
`final_results`	boolean	no	Default `false`. `true` sends one `call.processed` with the finished transcript after the call ends.
`tier`	string	no	`t1` \| `t3` \| `t5`. Defaults to your key’s tier, which is your company’s plan, so leave it out. Any other tier is refused with `403 contract_unavailable`. Before your company goes live, every call runs at `t5`, whatever you send. See tiers.

cURL
Python
Node.js

curl -X POST https://sandbox.voice.miraiminds.co/v2/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8842-confirm-1" \
  -d '{
    "agent_id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
    "to": "+919876543210",
    "variables": { "customer_name": "Rahul", "order_id": "8842" },
    "webhook_url": "https://example.com/mirai/webhook",
    "max_duration_secs": 240
  }'

import os, httpx

API = "https://sandbox.voice.miraiminds.co"
auth = {"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"}

r = httpx.post(
    f"{API}/v2/calls",
    headers={**auth, "Idempotency-Key": "order-8842-confirm-1"},
    json={
        "agent_id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
        "to": "+919876543210",
        "variables": {"customer_name": "Rahul", "order_id": "8842"},
        "webhook_url": "https://example.com/mirai/webhook",
        "max_duration_secs": 240,
    },
    timeout=30,
)
if r.status_code == 402:
    raise RuntimeError(r.json()["error"]["message"])  # top up the wallet
call = r.raise_for_status().json()
print(call["id"], call["status"])  # call_01JZQ9B4M8N3P6R2S5T7V9W1YA queued

const API = "https://sandbox.voice.miraiminds.co";
const auth = { Authorization: `Bearer ${process.env.MIRAI_API_KEY}` };

const res = await fetch(`${API}/v2/calls`, {
  method: "POST",
  headers: {
    ...auth,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-8842-confirm-1",
  },
  body: JSON.stringify({
    agent_id: "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
    to: "+919876543210",
    variables: { customer_name: "Rahul", order_id: "8842" },
    webhook_url: "https://example.com/mirai/webhook",
    max_duration_secs: 240,
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.id, body.status); // call_01JZQ9B4M8N3P6R2S5T7V9W1YA queued

202 Accepted

{
  "id": "call_01JZQ9B4M8N3P6R2S5T7V9W1YA",
  "status": "queued",
  "events_url": "https://sandbox.voice.miraiminds.co/v2/calls/call_01JZQ9B4M8N3P6R2S5T7V9W1YA/events?token=…"
}

202 means the call is admitted to the queue. The phone has not rung yet. The full call object is available from GET /v2/calls/{id}.

Field	Description
`id`	The call ID. It is the `data.call.id` of every webhook for this call.
`status`	`queued`.
`events_url`	The call’s live event stream: the agent’s state and each turn while the call runs. It carries its own read-only token, valid for the call’s maximum duration plus one hour, so you can hand it to a browser without your API key.

A phone call’s 202 has no ws_url and no transport. A browser call’s 202 adds them, because the page also needs an audio link:

202 Accepted (channel web)

{
  "id": "call_01K8B2M4Q6S8T0V2X4Z6A8C0EG",
  "status": "queued",
  "transport": "web",
  "ws_url": "wss://sandbox.voice.miraiminds.co/v2/calls/call_01K8B2M4Q6S8T0V2X4Z6A8C0EG/media?token=…",
  "ws_url_expires_at": "2026-09-27T10:05:00Z",
  "events_url": "https://sandbox.voice.miraiminds.co/v2/calls/call_01K8B2M4Q6S8T0V2X4Z6A8C0EG/events?token=…"
}

Field	Description
`transport`	`web`.
`ws_url`	The audio socket. Single use; connect within 5 minutes.
`ws_url_expires_at`	When an unused `ws_url` stops working.
`events_url`	The live event stream. Reusable for the call and for one hour after it ends.

Errors

Status	`error.code`	Cause
`400`	`invalid_request`	Missing `agent_id`/`to`, `to` not E.164, `to` sent with `channel: "web"`, `max_duration_secs` out of range, invalid `metadata`, `first_message`, `system_prompt`, `timing` or `call_settings`, or `system_prompt` sent with `channel: "realtime"`. `error.message` names the field.
`401`	`unauthorized`	Bad or missing key
`402`	`insufficient_balance`	Wallet cannot cover the first minute at your tier. We check before we dial, so there is no partial charge. See Wallet.
`403`	`recording_disabled`	`recording_enabled: true` on a workspace whose recording is turned off
`403`	`contract_unavailable`	The call is not covered by an active production contract: `tier` is not your company’s plan, or the company has not finished going live. See setting the tier.
`404`	`not_found`	`agent_id` does not exist in your workspace (including one that exists in someone else’s)
`409`	`duplicate_call`	A request with this `Idempotency-Key` is still being processed. See idempotency.
`409`	`number_retired`, `number_resting`, `pool_busy`, `pool_unavailable`	The number or pool you chose cannot place the call right now. Nothing was dialled and no other number was used. `pool_busy` carries `Retry-After`. See phone numbers and pools.
`400`	`invalid_flow`	`agent_id` is a node-based agent and your tier’s model cannot run flows. The body lists the problem with its path. Nothing was dialled.
`409`	`flow_agent_voice_only`	A text chat (`channel: "text"`) with a node-based agent. Node-based agents run on `phone` and `web`.
`409`	`flow_first_message_unsupported`	`first_message` sent for a node-based agent. Its start node’s `greeting` opens the call; personalise it with `variables`.
`409`	`flow_system_prompt_unsupported`	`system_prompt` sent for a node-based agent. Its nodes’ prompts run the call; personalise them with `variables`.
`429`	`rate_limited`	Request rate exceeded, or your queue is full (500 calls accepted and not yet ended); `error.message` says which. Going over your concurrency cap does not return 429: those calls wait in the queue. Honour `Retry-After`. See Limits.
`429`	`at_capacity`	Every line on the deployment is busy. `Retry-After: 30`. Nothing was charged.
`501`	`tier_unavailable`	`tier` names a tier that is not enabled on this deployment

Variables

variables is a flat map of string keys to string values. Each key replaces the matching {{key}} placeholder in the agent’s system_prompt and first_message, or in the call’s own system_prompt and first_message when you send them.

{ "variables": { "customer_name": "Rahul", "order_id": "8842" } }

Plain {{key}} placeholders match loosely: letters and digits only, case-insensitive, so {{Customer Name}}, {{customer_name}} and {{CustomerName}} all read the same variable. Only a Liquid expression with a filter ({{ key | upcase }}) needs the exact key.
A placeholder with no matching variable is replaced with an empty string. There is no error, and no {{braces}} are left for the agent to read aloud. Validate on your side.
Keep values short. They are part of the prompt, and the prompt is on the latency path.
Variables are static per call. There is no way to change them mid-call. On a browser call, an instruction can direct the agent mid-call instead.
On a node-based agent, variables fill the node prompts, the start node’s greeting and extraction prompts. Transition conditions are not filled in.

Per-call prompt

system_prompt on the call replaces the agent’s prompt for that call only. The agent is not changed, and the rest of its setup still applies to the call: its voice, language, opening line and tools. One agent with variables is still the simplest way to personalise calls, because the instructions stay the same and only the details change. Send a per-call prompt when each call needs different instructions, for example when your own system writes the script for each customer.

curl -X POST https://sandbox.voice.miraiminds.co/v2/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8842-redelivery-1" \
  -d '{
    "agent_id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
    "to": "+919876543210",
    "system_prompt": "You are Priya from Acme. {{customer_name}} missed the delivery of order {{order_id}} yesterday. Apologise once, offer a new slot tomorrow between 10:00 and 18:00, and confirm the delivery address. Keep replies to one or two short sentences. When the customer is done, thank them and end the call.",
    "variables": { "customer_name": "Rahul", "order_id": "8842" },
    "webhook_url": "https://example.com/mirai/webhook"
  }'

It holds 1 to 16,000 characters, the same ceiling as the agent’s prompt. A blank or longer prompt returns 400 invalid_request.
{{variable}} placeholders are filled from the call’s variables, as they are in the agent’s prompt, and checked by the same rule. If the agent declares an input_schema, every variable the prompt reads must be declared in it. An undeclared one returns 400 invalid_request.
It works on phone and web calls. A realtime session takes its instructions from the client’s session.update, so system_prompt on channel: "realtime" returns 400 invalid_request.
A node-based agent runs its nodes’ prompts, so it refuses a per-call prompt with 409 flow_system_prompt_unsupported.
We never return it: it is not on the call object and not in any webhook. To know later which prompt a call ran, store it on your side against the call id.
Keep it short. The prompt is on the latency path, and a long one adds delay well before it reaches the limit. See the prompting guide.

Call settings

call_settings sets the voice and the languages of one call. The agent and its saved revisions stay as they are.

curl -X POST https://sandbox.voice.miraiminds.co/v2/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8842-confirm-gu-1" \
  -d '{
    "agent_id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
    "to": "+919876543210",
    "variables": { "customer_name": "Mehul", "order_id": "8842" },
    "call_settings": { "voice_id": "sameer", "language": "gu", "secondary_languages": ["en"] }
  }'

Key	Description
`voice_id`	The voice the agent speaks in. It takes the same values as an agent’s `voice.voice_id`: `ashu`, `neha`, `shruti`, `sameer`, `munshi` or `tanvi`. See Voices.
`language`	The call’s main language, written the way an agent’s `language` is (`hi`, `gu`, `en-IN`), up to 35 characters. Speech recognition listens for it.
`secondary_languages`	Other languages the caller may speak. Up to 4 of `hi`, `en`, `gu`, `mr`, `bn`, `ta`, `te`, `kn`, `ml`, `pa` and `od`. A regional tag is read as its base code (`gu-IN` is `gu`), and duplicates and the main language are dropped. `[]` listens for the main language only.

Every key is optional. A key you leave out keeps the agent’s value. The settings apply from the agent’s first word, greeting included, on every channel. On a realtime session, the client’s session.update can still change them. language sets what speech recognition listens for, and our standby voice pronounces in it if it serves the call. It does not change your prompt. If the agent should reply in that language, say so in the prompt, for example with a variable. The older "voice": { "voice_id": "…" } on a request still works and means call_settings.voice_id. Send one or the other: both with different values is a 400.

Where the settings come from

call_settings is accepted in three places, with the same keys and rules. A call starts from the agent’s own values, and each later source wins, key by key:

Order	Source	Where you set it	In `sources`
1	The agent	`voice.voice_id`, `language` and `secondary_languages` on the agent	`agent`
2	Your request	`call_settings` on `POST /v2/calls`	`request`
3	A campaign contact	`call_settings` on the contact	`campaign`
4	Pre-call tools, in the order they run	A `call_settings` object in the tool’s result	`pre_call:<tool name>`

A request can set the voice, for example, and a pre-call tool that answers with only language then changes the language and keeps the request’s voice.

Bad values

On a request, a bad value is 400 invalid_request and nothing is dialled. The message names the key and, where there is a fixed list, the values allowed:

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "call_settings.voice_id \"priya\" is not a voice; it must be one of ashu, munshi, neha, sameer, shruti, tanvi"
  }
}

The same 400 answers a value of the wrong type, a blank value (leave the key out instead), an unknown key, a language longer than 35 characters, a secondary language outside the list, and more than 4 secondary languages. A campaign contact with a bad value is rejected on its own row, and the rest of the list goes in. A pre-call tool’s bad value never fails the call: the call keeps the value it had, and the tool’s receipt says which key was skipped and why.

On the call object

Every call shows the settings it runs with, the agent’s own values included, and who chose each one. They are on GET /v2/calls/{id}, on each call in GET /v2/calls and in data.call of every webhook.

{
  "call_settings": {
    "voice_id": "sameer",
    "language": "gu",
    "secondary_languages": ["en"],
    "sources": {
      "voice_id": "pre_call:user_lookup",
      "language": "pre_call:user_lookup",
      "secondary_languages": "agent"
    }
  }
}

Each value in sources is agent, request, campaign or pre_call:<tool name>. call.queued shows the settings before pre-call tools run, and every event from call.started on shows the ones the call used. Calls from before per-call settings existed have no call_settings, and neither does an incoming call turned away before an agent was found.

Metadata

metadata holds your own identifiers, so every webhook can be matched to your records without a lookup table:

{ "metadata": { "session_id": "sess_8f2c41", "user_id": "usr_1042" } }

Up to 16 keys. A key is 1 to 40 characters: ASCII letters, digits and _, ., :, -, starting with a letter, digit or _.
Values are strings of up to 256 characters. The whole object, serialized, is at most 4 KB.
It is fixed when the call is created and returned unchanged on the call object and in data.call of every webhook for the call.
The agent never sees it. Anything the agent should use goes in variables.
A call without metadata has no metadata field at all.
Put IDs in it, not secrets or personal data: it travels on every webhook.

Invalid or oversized metadata returns 400 invalid_request.

Idempotency

Send Idempotency-Key with a value derived from your own domain object:

-H "Idempotency-Key: order-8842-confirm-1"

If we have seen that key in the last 24 hours, we replay the original response byte for byte and place no second call. This is the safe way to retry a request that timed out. A network timeout does not tell you whether the call was placed, and without the key a retry makes the customer’s phone ring twice. The replay repeats events_url while its token is valid, and leaves it out after that. Your API key still opens the live event stream. The key is scoped to your workspace. Reusing a key with a different body still replays the original response, so pick keys that are unique per intended call. There is one window where a reused key does not replay: while the first request with that key is still being processed, there is no stored response to replay yet, so the second request gets 409 duplicate_call. It means the first request is already in flight and no second call was placed. Retry a moment later to get the original response, or wait for the webhook.

Get a call

GET /v2/calls/{id}

cURL
Python
Node.js

curl https://sandbox.voice.miraiminds.co/v2/calls/call_01JZQ9B4M8N3P6R2S5T7V9W1YA \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

import time

TERMINAL = {"completed", "voicemail", "no_answer", "busy", "failed", "timeout", "aborted"}

def wait_for_call(call_id: str, timeout_secs: int = 600) -> dict:
    """Prefer webhooks. Poll only when you cannot host an endpoint."""
    deadline = time.monotonic() + timeout_secs
    while time.monotonic() < deadline:
        call = httpx.get(f"{API}/v2/calls/{call_id}", headers=auth, timeout=30) \
                    .raise_for_status().json()
        if call["status"] in TERMINAL:
            return call
        time.sleep(5)
    raise TimeoutError(call_id)

const TERMINAL = new Set([
  "completed", "voicemail", "no_answer", "busy", "failed", "timeout", "aborted",
]);

async function waitForCall(callId, timeoutMs = 600_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const call = await fetch(`${API}/v2/calls/${callId}`, { headers: auth })
      .then((r) => r.json());
    if (TERMINAL.has(call.status)) return call;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error(`timed out waiting for ${callId}`);
}

200 OK returns the call object. You get 404 not_found both for an unknown ID and for an ID that belongs to another workspace. The two responses are identical on purpose.

Poll no faster than every 5 seconds, and only when you cannot receive webhooks. Polling counts against your rate limit; webhooks do not.

Get the transcript

GET /v2/calls/{id}/transcript

Returns what was said, as turns, once the call has ended.

curl https://sandbox.voice.miraiminds.co/v2/calls/call_01K7Q9B4M8N3P6R2S5T7V9W1YA/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

200 OK

{
  "call_id": "call_01K7Q9B4M8N3P6R2S5T7V9W1YA",
  "turns": [
    {
      "role": "assistant",
      "text": "नमस्ते Rohit जी, मैं Acme Retail से Priya बोल रही हूँ। एक मिनट बात कर सकती हूँ?",
      "start_ms": 420,
      "end_ms": 4980
    },
    { "role": "user", "text": "हाँ बोलिए", "start_ms": 5640, "end_ms": 6390 },
    {
      "role": "assistant",
      "text": "आपका order AC-88213 kal shaam 6 baje deliver hoga. Ye slot theek hai?",
      "start_ms": 7010,
      "end_ms": 14880
    },
    { "role": "user", "text": "haan theek hai", "start_ms": 15900, "end_ms": 17240 }
  ]
}

Field	Notes
`role`	`assistant` or `user`. Nothing else appears, because internal steps are not part of the conversation.
`text`	The turn as spoken. Hindi, Hinglish and English arrive as they were said; nothing is translated.
`start_ms`, `end_ms`	Milliseconds from the start of the recording, so a turn lines up with the audio. `end_ms` can be `null` on the last turn of a call that was cut off.

404 not_found while the call is still running, and for a call that produced no speech at all. Check transcript_status on the call object to tell them apart: pending, empty or failed. For browser calls, final results deliver the same turns by webhook as soon as they are ready.

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "transcript not available (call still in progress or produced no speech)"
  }
}

Get the recording

GET /v2/calls/{id}/recording

Returns 302 to a signed, time-limited URL for the call’s audio (WAV). Follow the redirect. Most HTTP clients do by default; curl needs -L.

curl -L https://sandbox.voice.miraiminds.co/v2/calls/call_01K7Q9B4M8N3P6R2S5T7V9W1YA/recording \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -o call.wav

302 Found

Location: https://storage.miraiminds.co/voice-agents/production/call_records/call_01K7Q9B4M8N3P6R2S5T7V9W1YA/call.wav?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=…

The signed link expires in 15 minutes and it is a bearer token.Use it to fetch the recording right away. To get the audio later, store the call_id and ask again; do not store the link. Anyone holding it can fetch the audio until it expires, so treat it exactly as you would treat the recording.

404 not_found while the call is running, for a call that produced no audio, and for one whose audio was never stored, which includes every call created with recording_enabled: false. recording_available on the call object tells you which requests are worth making. Transcripts and recordings are kept for 90 days, the same as the call record. Pull anything you need to keep longer into your own system.

Abort a call

POST /v2/calls/{id}/abort

Cancels a call that has not ended yet. Abort is accepted while the call is queued, dialing or in_progress. If the call is live, the SIP server hangs it up mid-conversation. On a browser call, abort also closes the browser’s audio socket. Only a call that has already reached a terminal status is refused. Abort is immediate and silent. To end a browser call with a spoken goodbye, send a close control instead.

curl -X POST https://sandbox.voice.miraiminds.co/v2/calls/call_01JZQ9B4M8N3P6R2S5T7V9W1YA/abort \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

202 Accepted

{ "id": "call_01JZQ9B4M8N3P6R2S5T7V9W1YA", "status": "aborted" }

202 means the cancel was signalled. The call reaches aborted shortly after with ended_reason: "aborted-by-api", and a call.aborted event fires. An aborted call is billed for the time it was connected, at the same rate and in the same blocks as any other call. An abort while the call is still queued or ringing costs nothing.

Status	`error.code`	Cause
`404`	`not_found`	Unknown call ID, or a call in another workspace
`409`	`conflict`	The call has already ended (its status is terminal), so there is nothing to abort

Live control and events

Three more endpoints work while a call runs. Every call has the live event stream. Live control is for browser calls; Browser calls covers it in full.

Endpoint	What it does
`GET /v2/calls/{id}/events`	The live event stream (Server-Sent Events): agent state, each completed turn and, for a node-based agent, each step. Every call has one: phone calls you place, campaign and inbound calls, browser calls and realtime sessions. Opened with the `events_url` from create, or with your API key. See Live events.
`POST /v2/calls/{id}/control`	Send an `instruction` the agent follows from its next reply, or `close` the call with a spoken goodbye. Browser calls in progress only. See live control.
`GET /v2/calls/{id}/control/{control_id}`	Read a control’s current status: `pending`, `applied`, `rejected` or `failed`.

Status	`error.code`	Cause
`400`	`unsupported_channel`	Control sent to a call that is not a browser call
`401`	`invalid_token`	The `token` in a media or events link is unknown, expired, already used, or for another call
`404`	`not_found`	Unknown call or control ID, or one in another workspace
`409`	`call_not_active`	Control sent to a call that is still `queued` or has already ended

List calls

GET /v2/calls?agent_id=&status=&from=&to=&limit=&cursor=

Query param	Description
`agent_id`	Only calls run by this agent.
`status`	Filter by one status.
`from`	RFC 3339 lower bound on `created_at`, inclusive.
`to`	RFC 3339 upper bound on `created_at`, exclusive.
`limit`	1–100, default 20.
`cursor`	From `next_cursor` of the previous page.

curl -G https://sandbox.voice.miraiminds.co/v2/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "agent_id=agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ" \
  --data-urlencode "status=completed" \
  --data-urlencode "from=2026-07-01T00:00:00Z" \
  --data-urlencode "limit=100"

200 OK

{
  "data": [
    {
      "id": "call_01K7Q9B4M8N3P6R2S5T7V9W1YA",
      "object": "call",
      "agent_id": "agt_01K7Q9F3K7M2N5P9R4T6V8W0XZ",
      "to": "+919876543210",
      "status": "completed",
      "tier": "t3",
      "ended_reason": "customer-ended-call",
      "created_at": "2026-08-10T09:15:00Z",
      "started_at": "2026-08-10T09:15:02Z",
      "ended_at": "2026-08-10T09:16:38Z",
      "duration_secs": 96,
      "cost_inr": 5,
      "recording_available": true,
      "transcript_available": true,
      "analysis": null
    }
  ],
  "has_more": true,
  "next_cursor": "MTc4ODk2MTQ1Mi4zMzA5MTc6Y2FsbF8wMUs3UTlCNE04TjNQNlIyUzVUN1Y5VzFZQg"
}

Results are newest first by created_at, inbound and outbound calls together. Each call in the list gives its total as cost_inr. For the full cost block with its rates, read the call with GET /v2/calls/{id}. next_cursor is an opaque string; send it back as cursor unchanged. See pagination.

Use the list endpoint for reconciliation and reporting. To drive your application state, use webhooks.

Count calls

GET /v2/calls/summary?from=&to=

How many calls your workspace has made and taken, without paging through them. These are the same figures the console’s Calls page shows.

Query param	Description
`from`	Optional. RFC 3339 lower bound on `created_at`, inclusive.
`to`	Optional. RFC 3339 upper bound on `created_at`, exclusive.

Leave both out to count every call. The window works the same way as on GET /v2/calls, so a count and a list over the same window cover the same calls.

curl -G https://sandbox.voice.miraiminds.co/v2/calls/summary \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "from=2026-10-01T00:00:00Z"

200 OK

{
  "object": "call_summary",
  "total": 1240,
  "by_channel": { "phone": 1096, "web": 118, "text": 20, "realtime": 6 },
  "by_direction": { "outbound": 1012, "inbound": 228 },
  "duration_secs": 98412,
  "from": "2026-10-01T00:00:00Z",
  "to": null
}

Field	Type	Description
`total`	integer	Every call in the window.
`by_channel`	object	The same calls split by `channel`. The four counts add up to `total`.
`by_direction`	object	The same calls split into `outbound` and `inbound`. They add up to `total`. Incoming calls from before mid-October 2026 may be counted as outbound, because their records do not say.
`duration_secs`	integer	Total live time across those calls, in seconds. A call that never connected adds nothing.
`from`, `to`	string \| null	The window you asked for, in UTC. `null` when you didn’t set that side.

Every count is always present, even when it’s zero.

Status	Code	When
`400`	`invalid_request`	`from` or `to` is not an RFC 3339 timestamp.
`503`	`summary_unavailable`	We couldn’t read the totals just now. Try again. Don’t read it as zero calls.

Start here

Build

Prompting

Speech API

Text to speech

Speech to text

Language model

Money

Reference

Calls API: place and track AI phone calls

The call object

Flow outcome

Statuses

Ended reasons

Create a call

Request

Errors

Variables

Per-call prompt

Call settings

Where the settings come from

Bad values

On the call object

Metadata

Idempotency

Get a call

Get the transcript

Get the recording

Abort a call

Live control and events

List calls

Count calls

​The call object

​Flow outcome

​Statuses

​Ended reasons

​Create a call

​Request

​Errors

​Variables

​Per-call prompt

​Call settings

​Where the settings come from

​Bad values

​On the call object

​Metadata

​Idempotency

​Get a call

​Get the transcript

​Get the recording

​Abort a call

​Live control and events

​List calls

​Count calls

The call object

Flow outcome

Statuses

Ended reasons

Create a call

Request

Errors

Variables

Per-call prompt

Call settings

Where the settings come from

Bad values

On the call object

Metadata

Idempotency

Get a call

Get the transcript

Get the recording

Abort a call

Live control and events

List calls

Count calls