Get Batch Call | SpeechifyAI API

Returns the batch call. List its recipients with GET /v1/agents/batch-calls/{batch_call_id}/recipients.

Authentication

AuthorizationBearer

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

Path parameters

batch_call_idstringRequired

Batch call ID.

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.

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

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

1	{
2	"id": "batch_01kj8fy7kphhchfcfc230hgv12",
3	"agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
4	"name": "Example name",
5	"status": "pending",
6	"total": 10,
7	"completed": 7,
8	"failed": 1,
9	"created_at": "2026-06-24T18:03:11Z",
10	"updated_at": "2026-06-24T18:03:11Z",
11	"phone_number_id": "phone_01jqr8x9zg5k2m3n4p5q6r7s8t",
12	"error": "example",
13	"started_at": "2026-06-24T18:03:11Z",
14	"ended_at": "2026-06-24T18:03:11Z",
15	"scheduled_at": "2026-06-24T18:03:11Z",
16	"ringing_timeout_ms": 5000
17	}

$	curl https://api.speechify.ai/v1/agents/batch-calls/batch_01jqr8x9zg5k2m3n4p5q6r7s8t \
>	-H "Authorization: Bearer <token>"

Authentication

Path parameters

Headers

Response headers

Response

Errors