API ReferenceTelephonyBatch calls

Cancel Batch Call

Beta
Cancel a batch call. Moves any non-terminal batch - `pending` (including one deferred to a future `scheduled_at`) or `running` - to `cancelled` and stops the dispatcher from dialing the not-yet-dialed recipients (they become `cancelled`; calls already placed keep their outcome). Idempotent (§16): cancelling an already-terminal batch (`completed` / `failed` / `cancelled`) returns it unchanged. 404 only when the batch id is unknown.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

batch_call_idstringRequired
Batch call ID.

Headers

Speechify-VersionstringOptional

Response headers

X-Request-IDstring
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The (possibly already-terminal) batch call.

idstringformat: "^batch_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (batch_<26 char Crockford base32>). URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

agent_idstringformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (agent_<26 char Crockford base32>) of the agent that will run the batch.

namestring

Human-readable batch name.

statusenum

Lifecycle status. A batch deferred to a future time is pending with a non-null scheduled_at; it moves to running once the scheduled time arrives and the dispatcher starts dialing.

totalinteger

Total number of recipients (the progress denominator).

completedinteger
Recipients successfully dialed.
failedinteger
Recipients that failed.
created_atdatetime
updated_atdatetime
phone_number_idstring or nullformat: "^phone_[0-9a-hjkmnp-tv-z]{26}$"

Caller-ID override. When set, prefixed wire identifier (phone_<26 char Crockford base32>) of the phone number to use; falls back to the agent’s bound number when null.

errorstring
Populated when the batch itself fails.
started_atdatetime or null
When the dispatcher started dialing.
ended_atdatetime or null
When the last recipient was resolved.
scheduled_atdatetime or null
If set, the batch waits until this time before dialing.
ringing_timeout_msinteger or null

Per-call ringing timeout in milliseconds applied to every recipient in the batch. Null when the batch uses the 30s default.

Errors

401
Unauthorized Error
404
Not Found Error