Limits & compliance

Two kinds of limit apply to you: our technical limits, which we enforce, and India’s regulatory rules, which you are responsible for.

Rate limits

Limits are per secret key.

Limit	Pilot default	Applies to	Over the limit
Request rate	10 requests/second, burst 20	all `/v2/*` endpoints	`429 rate_limited`
Concurrent live calls	5	calls in `dialing` or `in_progress`	the call queues
Queue depth	500	calls accepted and not yet ended	`429 rate_limited`
TTS requests in flight	10 per workspace	`/v1/audio/speech`, `/v2/tts`, and each sentence being synthesised on a TTS stream	HTTP: `429 at_capacity`. Stream: the sentence waits up to 3 seconds, then `error` `at_capacity`.
Open TTS streams	200 per workspace	WebSockets on `/v1/audio/speech/stream`	`429 at_capacity` with `Retry-After: 5`
Speech-to-text sessions	10 per workspace	`POST /v1/audio/transcriptions` requests in flight and open WebSockets on `/v1/audio/transcriptions/stream`, together	`429 at_capacity` with `Retry-After`
Flow generations	30 per hour per workspace	`POST /v2/agents/flow/generate`	`429 rate_limited` with `Retry-After`
Recording transcriptions	60 per hour per workspace	`POST /v2/agents/flow/transcribe`	`429 rate_limited` with `Retry-After`
Offline transcriptions	120 per hour per workspace	`POST /v2/transcriptions`	`429 rate_limited` with `Retry-After`
Unfinished offline transcriptions	20 per workspace	jobs not yet `completed` or `failed`	`429 at_capacity` with `Retry-After: 30`

Pilot keys are provisioned individuallyThe numbers above are the defaults a new pilot key is issued with, and yours may differ. Confirm your actual ceilings with your account contact before you size a campaign. Higher concurrency only needs a provisioning change, so ask for it.

Request rate

Exceeding the request rate returns 429 with error.code: rate_limited and a Retry-After header in seconds. This limit measures how fast you call the API, not how many phones are ringing.

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded, retry in 0.4s"
  }
}

Concurrency

Call concurrency does not produce a 429. A POST /v2/calls beyond your concurrent-call ceiling is still accepted with 202. It waits in queued until a slot frees and then dials, so no call is rejected or lost. On the call path, 429 is request-rate only. (Text to speech over HTTP is the one exception: it has no queue, so it refuses the request.) So the ceiling paces your calls instead of refusing them. That has two consequences:

A queued call’s phone rings later than you asked. If a call is only useful inside a window, check status before you assume it went out, or do not submit it until you have the capacity.
Submitting a burst does not fail; it builds a queue that drains at your concurrency.

Queue depth

The queue itself is bounded. Once you have 500 calls accepted and not yet ended, further POST /v2/calls return 429 rate_limited with a Retry-After header until calls drain. The message names the ceiling, so you can tell it apart from a request-rate 429:

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "queue depth limit reached for this workspace (500 calls accepted and not yet ended, limit 500); wait for calls to drain or ask ops to raise it"
  }
}

Both limits share the rate_limited code on purpose, because your client should handle them the same way: honour Retry-After and retry. Read error.message if you want to log which one you hit. The count covers calls accepted and not yet ended. That is queued plus the few calls actually dialing or in_progress, not queued alone. With a concurrency of 5, the difference is at most 5 calls. Queue depth is provisioned per workspace, like concurrency. If a campaign needs to submit more than 500 rows in one batch, ask your Mirai contact before the campaign starts, not during it. Even so, it is better to keep our queue short and hold the rest on your side, where you can reorder, cancel and re-prioritise it. The simplest correct pattern looks like this:

# keep N calls in flight; refill as terminal webhooks arrive
in_flight = 0
MAX_IN_FLIGHT = 5   # your provisioned concurrency

def on_terminal_webhook(event):
    global in_flight
    in_flight -= 1
    pump()

def pump():
    global in_flight
    while in_flight < MAX_IN_FLIGHT and queue:
        place_call(queue.pop())
        in_flight += 1

Do not drive pacing off a fixed sleep(). Answer rates vary by hour, and a fixed delay either wastes capacity or hammers the limit.

Text to speech

Every workspace has one pool of synthesis slots, 10 by default. An HTTP request to the speech API holds a slot while it runs, and so does each sentence on a WebSocket stream while it is being synthesised. An open socket that is not speaking holds none. The two handle a full pool differently. The HTTP endpoint has no queue, so it refuses the request. On a stream, a sentence whose turn has come waits up to 3 seconds for a slot, in a queue shared by all your sockets, before it fails.

Limit	Default	Over the limit
Requests in flight	10 per workspace, shared by HTTP requests and stream sentences	HTTP: `429 at_capacity` with `Retry-After`; the request is refused, not queued. Stream: the sentence waits up to 3 seconds, then gets an `error` event with `at_capacity` and `retry_after_secs`.
`input` length	2,000 characters per HTTP request	`400 invalid_request`. Split longer text.
Request rate	10 requests/second, burst 20, per key	`429 rate_limited` with `Retry-After`. Opening a socket or minting a stream token counts as a request.

at_capacity can also come from a deployment-wide ceiling when the speech node is saturated. It is the same code, and you handle it the same way. A refused request holds no slot and is never charged. The limit is raised on request, with no change to your code. If you run many calls at once, ask your Mirai contact for a limit a little above your peak number of simultaneous calls: each speaking call needs a slot most of the time, and it starts its next sentence shortly before the current one ends. Streams have their own limits:

Thing	Limit
Open sockets	200 per workspace. More returns `429 at_capacity` with `Retry-After: 5` before the upgrade.
Stream token	Valid for 60 seconds, opens one socket.
One message	64 KB
Text waiting to be spoken	10,000 characters per socket (`queue_full`)
Open contexts	64 per socket (`too_many_contexts`)
One sentence	250 characters. Longer text with no sentence end is cut.
Idle socket	Closed after 120 seconds with no message from you and nothing playing
Socket lifetime	1 hour
Keepalive	We ping every 20 seconds and drop a client that has not answered for 60 seconds.

See Streaming text to speech for what each limit does to an open socket.

Speech to text

A workspace can run 10 speech-to-text sessions at once. Each HTTP request is a session while it runs, and so is each open socket. One more returns 429 at_capacity with Retry-After and costs nothing; a socket is refused before the upgrade. The limit is raised on request, with no change to your code.

Thing	Limit
Sessions at once	10 per workspace, HTTP and socket together
One HTTP clip	25 MB (over it, `413 request_too_large`) and 120 seconds of audio (over it, `413 audio_too_long`). Send longer recordings to offline transcription.
Stream token	Valid for 60 seconds, opens one socket. Up to 20 per mint request.
One `audio_input` on the socket	128,000 bytes of raw audio, counted before base64 (4 seconds of 16 kHz PCM). Over it, a fatal `audio_too_large` and close code 1011.
One utterance on the socket	60 seconds with manual endpointing. Over it, a fatal `utterance_too_long`, close code 1011, and no final for that utterance. Send `speech_end` at a pause at least every 25 seconds. With `vad` endpointing we cut long speech for you.
Utterances waiting for a final	8
Idle socket	Closed after 120 seconds with no message from you. `ping` keeps it open.
Session length on the socket	1 hour
Request rate	10 requests/second, burst 20, per key. Opening a socket and minting tokens count as requests too.

See the STT quickstart and the WebSocket reference for what each limit does.

Payload and duration ceilings

Thing	Limit
Request body	1 MB
`system_prompt`	16,000 characters, on the agent or per call
`first_message`	500 characters, on the agent or per call
`variables`	32 keys, 512 characters per value
`metadata`	16 keys; key 1–40 characters (ASCII letters, digits, `_` `.` `:` `-`; starts with a letter, digit or `_`); value 256 characters; 4 KB serialized
`max_duration_secs`	30–1800, default 300
`webhook_url`	HTTPS only, 2,048 characters
Idempotency key	255 characters, 24-hour window
TTS `input`	2,000 characters per request
Speech-to-text clip	25 MB and 120 seconds of audio per `POST /v1/audio/transcriptions`
Language model request	100 messages, 16,000 characters of message text and 16 tools per `POST /v2/chat/completions`; replies stop at 400 tokens, or up to 1,024 with `max_tokens`; 16 requests running at once per workspace

Invalid values return 400 invalid_request.

Call timing

max below is the call’s effective max_duration_secs. See timing policy.

`timing` field	Limit
`wrap_up_secs_before_end`	10 to `max` − 10
`close_secs_before_end`	5 to `max` − 10, and smaller than `wrap_up_secs_before_end` when both are set
`user_silence_close_secs`	15–600
`wrap_up_instruction`	1,000 characters
`close_message`, `user_silence_message`	500 characters each

Live events

These apply to every call’s live event stream: phone, campaign, inbound, browser and realtime.

Thing	Limit
Events link (`events_url`)	Reusable. Its token is valid for the call’s maximum duration plus one hour.
Live event replay	Kept for one hour after the call ends.

Browser calls

Thing	Limit
Audio link (`ws_url`)	Single use. Connect within 5 minutes of creating the call.
Control `instruction` text	1–1,000 characters
Control `close` message	500 characters
Control acknowledgement	`200` within 3 seconds, otherwise `202 pending`
Final results inline transcript	512 KB. Larger transcripts arrive as `fetch_required`.

Node-based agents

We check a node-based agent’s flow on every save. A flow over a graph limit returns 400 invalid_flow with the path of each problem. A generation or transcription request over its limits returns 400 invalid_request.

Thing	Limit
Nodes	2–20: exactly one `startCall`, at least one `endCall`, at most one `globalNode`
Transitions	1–40
Graph size	100 KB as JSON, with each non-ASCII character counted as its 6-byte escape
Node `name`	80 characters
Node `prompt`	16,000 characters
`greeting`	1,500 characters
Extraction variables	12 per node; `prompt` 2,000 characters
Transition `condition`	2,000 characters
Node IDs, labels, variable names	64 characters: a letter or underscore, then letters, digits or underscores
Generation `brief`	1–20,000 characters; optional when `examples` are sent
Generation `examples`	2–10 call transcripts, each 1–40,000 characters, 200,000 characters together
Generation `language`	32 characters
Generation `model`	`gemini-3.8-flash` (default), `gpt-6-sol` or `claude-opus-5.5`
Transcription `file`	One recording per request: 25 MB and 15 minutes; mp3, wav, m4a, ogg/opus, webm, flac, aac or amr
Transcription `language`	32 characters

A flow generation typically takes 15 to 60 seconds, depending on the model; set a client timeout of a few minutes. When the generator is busy with other requests, it answers 429 rate_limited with Retry-After, and that refusal does not count against the hourly limit. A transcription typically takes 5 to 10 seconds for a two-minute call, and the transcriber answers 429 the same way when it is busy. Each generation and transcription is charged to your wallet at the provider’s reported cost plus 20%; see AI flow drafts.

Offline transcription

Offline transcription checks the job count and your wallet before it reads the recording, and nothing is charged for a refused request.

Thing	Limit
Uploaded file	45 MB. Over it, `413 request_too_large`. Send a larger file by link.
Recording sent by `url`	200 MB. Over it, `413 request_too_large`.
Length of a recording	120 minutes. A longer recording is accepted, then the job fails with `audio_too_long`, free.
`context`	2,000 characters
`vocabulary`	200 terms of up to 100 characters each
Time to finish	24 hours after the job was accepted. After that, the job fails with `timed_out`, free.

Campaign ceilings

Campaigns carry their own bounds, all enforced at the API edge with 400 invalid_request.

Thing	Limit	Notes
`contacts` per request	1000 rows	Applies to both create and `POST /contacts`. For a longer list, call it repeatedly; a running campaign accepts new rows.
`slots`	1–4 per campaign	`HH:MM` local. A zero-length slot is rejected, not read as “all day”.
`max_concurrent`	1–50	Also bounded by your workspace concurrency. Two campaigns share one ceiling.
`retry_count`	0–5	Retries after the first attempt.
`re_attempt_period_secs`	60–86,400	1 minute to 24 hours.
`max_duration_secs`	30–1800	Defaults to the agent’s.
`budget_paise`	positive integer	Paise, not rupees. Omit for no cap.
`name`	120 characters
Contact `variables`	32 keys, 512 chars per value	Same rule as call variables.

Bad contact rows do not fail the batch: they come back by index in contacts_rejected. Only exceeding 1000 rows fails the whole request. Long prompts add latency well before they reach a size limit. The stack is tuned for prompts in the hundreds of tokens, not thousands.

Timeouts

Stage	Behaviour
API request	If there is no response within 30 seconds, treat the request as failed and retry with the same `Idempotency-Key`.
Ring / answer	~60 seconds. If no media arrives by then, the result is `no_answer`.
Call duration	Ends at `max_duration_secs` with `status: timeout`.
Browser connect	5 minutes after the call is created. If no audio connects, the call ends `failed` with `ended_reason: "no-media"` and is not billed.
Flow generation	Typically 15–20 s on Gemini 3.8 Flash, 20–60 s on GPT-6 Sol and 25–35 s on Claude Opus 5.5; up to a minute from example calls. Set a client timeout of a few minutes.
Recording transcription	Typically 5–10 s for a two-minute call, plus the upload. Set a client timeout of a few minutes.
Final results	`call.processed` follows the terminal event once the transcript settles (within about 2 minutes of the call ending) and any analysis and post-call tools finish.
Webhook delivery	Your endpoint should answer in well under a second. We treat slow responses as failures and retry them.

Data retention

Data	Retained
Call record (status, duration, cost)	90 days
Call recordings and transcripts	90 days, then deleted
Wallet ledger	12 months
Campaigns and their contact rows	For the life of the workspace
Offline transcription audio	Not kept. An upload passes through a temporary file that is deleted when the request ends, a file sent by link is fetched once, and the transcription service deletes the recording once it has decoded it.
Offline transcripts	Kept by the transcription service so that `GET /v2/transcriptions/{id}` can return them, with no published retention period. There is no endpoint to delete one yet.

You can fetch recordings and transcripts through the API with GET /v2/calls/{id}/recording and /transcript. Pull anything you need to keep beyond 90 days into your own system. To store no audio, create calls with recording_enabled: false, or ask us to turn recording off for your whole workspace. Save your own copy of each offline transcript when its job completes. If a transcript is no longer available, its job still reads completed with its cost, but without the text. To have a transcript removed, write to help@miraiminds.co.

India calling rules

Under Indian telecom regulation you are the sender: the obligations for commercial voice calls sit with the business placing them, not with the platform carrying them. This page is not legal advice, and it does not replace your own compliance review.

Calling window

Commercial and promotional voice calls are restricted to daytime hours. The window applied in practice is 09:00 to 21:00 IST, and several enterprise programmes tighten it further to 10:00 to 19:00. On a campaign, the platform enforces the window you declare. The platform evaluates timezone, start_date/end_date and 1 to 4 slots in local time on every dialling tick. Outside the window the campaign stays in play but rings nobody. Declaring 10:00 to 19:00 Asia/Kolkata is enough, and you do not need your own scheduler in front of it.

{
  "timezone": "Asia/Kolkata",
  "slots": [{ "start": "10:00", "end": "19:00" }]
}

On a single POST /v2/calls there is no window. A direct call is an explicit instruction to ring one number now, and it will dial at 02:00 IST if you ask it to. Enforce the window for those calls in your own scheduler:

from datetime import datetime
from zoneinfo import ZoneInfo

IST = ZoneInfo("Asia/Kolkata")

def within_calling_window(now=None) -> bool:
    now = now or datetime.now(IST)
    return 9 <= now.hour < 21

Get consent before you call. Consent should be explicit, recorded and revocable. Keep the record, because you will need to produce it when a complaint arrives.
Push your opt-outs to POST /v2/dnc. We enforce that list: every campaign checks it at dial time, so a number added mid-campaign is suppressed from that moment, marked suppressed in the report, and never billed. It does not apply to single POST /v2/calls, because a single call is an explicit instruction.
Scrub against the DND registry (TRAI’s Do Not Disturb / NCPR list) as well. We do not scrub against the national register for you, and our suppression list is not a substitute for it. A number can register between two campaigns.
Honour opt-outs immediately. If a customer says “stop calling me” during a call, that is an opt-out. Capture it and suppress the number on every channel it applies to.
Classify each campaign as transactional or promotional. A delivery confirmation to an existing customer is treated differently from a marketing pitch to a cold list. Do not put promotional content in a call you present as transactional.
Register as required. Commercial communication under TCCCPR 2018 runs through registered entities, headers and consent templates. Confirm your registration status with your telecom provider or counsel.

Disclosure that it is an AI

Tell people they are talking to an AI. Put the disclosure in the agent’s first_message or its opening turn:

{
  "first_message": "नमस्ते {{customer_name}}, मैं Acme की AI असिस्टेंट Priya बोल रही हूँ।"
}

Regulation worldwide is moving in this direction, and the disclosure costs you one clause. In practice it also reduces early hang-ups, because callers who feel misled are more likely to hang up than callers who were told.

Recording

If you record calls, say so in the opening turn and keep the recordings under the same retention and access controls as the rest of your customer data. If you do not need the audio, do not store it: recording_enabled: false keeps no recording for that call, and a workspace with recording turned off refuses recording_enabled: true with 403 recording_disabled.

What we do enforce

Rule	Enforced by us
E.164 destination format	✅ `400 invalid_request`
Wallet balance before dialling	✅ `402 insufficient_balance`
Request rate	✅ `429 rate_limited`
Concurrency ceiling	✅ over-cap calls wait in `queued`
TTS requests in flight	✅ `429 at_capacity` past 10 per workspace over HTTP; a stream sentence waits up to 3 seconds first
Queue depth	✅ `429 rate_limited` past 500 outstanding
Maximum call duration	✅ `status: timeout`
Recording off — per call or per workspace	✅ `recording_enabled: false`; `403 recording_disabled` on a workspace with recording off
Campaign budget cap	✅ campaign pauses, `pause_reason: budget_exhausted`
Calling window — campaigns	✅ `slots` + `timezone`, evaluated in local time every tick
Calling window — single `POST /v2/calls`	❌ your scheduler
Your own opt-out list	✅ `/v2/dnc`, checked at dial time on every campaign
National DND / NCPR scrubbing	❌ your list
Consent records	❌ your records
AI disclosure	❌ your prompt

If complaints against a workspace persist, we suspend its keys. This is our own policy rather than a regulatory one: we would rather suspend one campaign than lose the numbering range for everyone on the platform.

Start here

Build

Prompting

Speech API

Text to speech

Speech to text

Language model

Money

Reference

Rate limits

Request rate

Concurrency

Queue depth

Text to speech

Speech to text

Payload and duration ceilings

Call timing

Live events

Browser calls

Node-based agents

Offline transcription

Campaign ceilings

Timeouts

Data retention

India calling rules

Calling window

Disclosure that it is an AI

Recording

What we do enforce

​Rate limits

​Request rate

​Concurrency

​Queue depth

​Text to speech

​Speech to text

​Payload and duration ceilings

​Call timing

​Live events

​Browser calls

​Node-based agents

​Offline transcription

​Campaign ceilings

​Timeouts

​Data retention

​India calling rules

​Calling window

​Consent and DNC/DND

​Disclosure that it is an AI

​Recording

​What we do enforce

Rate limits

Request rate

Concurrency

Queue depth

Text to speech

Speech to text

Payload and duration ceilings

Call timing

Live events

Browser calls

Node-based agents

Offline transcription

Campaign ceilings

Timeouts

Data retention

India calling rules

Calling window

Consent and DNC/DND

Disclosure that it is an AI

Recording

What we do enforce