Voice Broadcast Number Status

Base URL for your account: https://cpaas.studio

GET POST /api/voice/v1/broadcast/status

Look up a broadcast's progress and per-number outcomes. Requires a key scoped to voice.broadcast or all. This is the endpoint you should poll after sending a broadcast.

Parameters

Param	Type	Required	Notes
`id`	string	one of id/reference	The id returned by Voice Broadcast's send response (data.id). Also accepts a per-number id, <id>-<n>, which narrows the response to that one recipient.
`reference`	string	one of id/reference	Your own label, if you supplied one on send. Not unique — resolves to your most recently created broadcast with that reference.
`number`	string	no	Restrict to a single recipient number. Normalized the same way numbers is on send.
`status`	string	no	One of the per-number status values. Filters the numbers list only — never the summary.
`from`	date	no	Restrict to numbers actually attempted in this window. A number still pending is excluded by either bound.
`to`	date	no	See from.
`page`	integer	no	Default 1.
`per_page`	integer	no	Default 100, max 500.

Request example

curl "https://cpaas.studio/api/voice/v1/broadcast/status?id=BC9QX4T7K2M" \
  -H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

<?php
$query = http_build_query(['id' => 'BC9QX4T7K2M']);
$ch = curl_init("https://cpaas.studio/api/voice/v1/broadcast/status?{$query}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Success response (`data`)

{
    "broadcast": {
        "id": "BC9QX4T7K2M",
        "reference": "order-4471",
        "status": "processed",
        "total_numbers": 4,
        "summary": {
            "answered": 1,
            "missed": 1,
            "failed": 0,
            "pending": 1,
            "skipped": 1
        },
        "created_at": "2026-08-15T12:00:00+00:00",
        "completed_at": "2026-08-15T12:05:00+00:00"
    },
    "numbers": [
        {
            "id": "BC9QX4T7K2M-1",
            "mobile": "9000000001",
            "status": "answered",
            "attempts": 1,
            "duration_seconds": 24,
            "billsec": 20,
            "answered_at": "2026-08-15T12:03:00+00:00",
            "updated_at": "2026-08-15T12:03:00+00:00"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 100,
        "total": 4,
        "total_pages": 1
    }
}

Errors

Code	Status	When
`BCAST_NOT_FOUND`	404	id/reference doesn't match any of your broadcasts. A per-number id whose base broadcast id doesn't resolve is the same code.
`REQ_VALIDATION_FAILED`	422	Missing both id and reference, an invalid status filter value, to earlier than from, or an out-of-range page/per_page.

Notes

"processed" means every number has been dispatched to the operator — it does NOT mean every call has been answered, or that results have come back yet. Check summary for outcomes.
Poll no more than once every few seconds per broadcast, and back off once broadcast.status reaches processed, partially_failed, or cancelled.
duplicate and invalid numbers were never dispatched — they are not a kind of failed, they never left the "accepted but not sendable" state.
no_audio: no audio could be prepared for this number. Not dialled, not charged. Text-to-speech broadcasts only (a message that failed to generate, or variable values that broke the template rules). Counted in summary.skipped, like duplicate and invalid.

Need more context? See Getting started for authentication, the response envelope, and the full error-code reference.

Get In Touch