Automations · Broadcasts

List broadcast recipients

Returns broadcast recipients, one page at a time.

GEThttps://api.pozy.ai/v1/broadcasts/{broadcastId}/recipients

listBroadcastRecipients

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the messages resource group disabled get 403 resource_group_disabled. Authentication

Path parameters

Name	Type	Notes
`broadcastId`required	string

Query parameters

Name	Type	Notes
`status`	string	One of `pending`, `sent`, `delivered`, `read`, `failed`
`limit`	integer	Default `50`
`skip`	integer	Default `0`

Example

curl -X GET "https://api.pozy.ai/v1/broadcasts/6ce1988a4c4f8bc6d3ca157a/recipients?limit=50" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/broadcasts/6ce1988a4c4f8bc6d3ca157a/recipients?limit=50", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/broadcasts/6ce1988a4c4f8bc6d3ca157a/recipients",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "limit": 50,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

successboolean
recipientsarray of object
14 child fields
- idstring
- contactIdstring
- channelIdstring
- platformIdentifierstring
- contactNamestring
  Can be null.
- statusstring
  One of pending, sent, delivered, read, failed.
- messageIdstring
- errorstring
- errorCodeinteger
  Can be null.
- errorExplanationstring
  Can be null.
- errorTraceIdstring
  Can be null.
- sentAtstring (date-time)
- deliveredAtstring (date-time)
- readAtstring (date-time)
paginationobject
- totalinteger
- limitinteger
- skipinteger
- hasMoreboolean
summaryobject
- totalinteger
- pendinginteger
- sentinteger
- deliveredinteger
- readinteger
- failedinteger

200 response

{
  "success": true,
  "recipients": [
    {
      "id": "6bfebd43ddc270f6d2c56fc5",
      "contactId": "642d31f43531ce7d44aa5013",
      "channelId": "6750a975638e9df035530f04",
      "platformIdentifier": "instagram",
      "contactName": "Acme",
      "status": "pending",
      "messageId": "62d191e7089bc48b8ea56b35",
      "error": "string",
      "errorCode": 1,
      "errorExplanation": "string",
      "errorTraceId": "6a226f257e731c76a6ddbb2e",
      "sentAt": "2026-10-02T09:00:00.000Z",
      "deliveredAt": "2026-10-02T09:00:00.000Z",
      "readAt": "2026-10-02T09:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 1,
    "skip": 1,
    "hasMore": true
  },
  "summary": {
    "total": 42,
    "pending": 1,
    "sent": 1,
    "delivered": 1,
    "read": 1,
    "failed": 1
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
404	not_found	Nothing with that id exists in your workspace.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

More in Broadcasts

GETList broadcasts POSTCreate broadcast draft GETGet broadcast details PATCHUpdate broadcast DELDelete broadcast POSTSend broadcast now POSTSchedule broadcast for later POSTCancel broadcast POSTAdd recipients to a broadcast