Skip to main content
TypeScript
Deprecated. Use POST /message/queues with broadcast_id in the request body instead

Authorizations

Authorization
string
header
required

Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.

Headers

x-phone
string
required

Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). The phone must be connected to the org and accessible by the API token.

Minimum string length: 1
Example:

"919876543210"

Query Parameters

broadcast_id
string
required

Id of the broadcast to fetch (a UUID), as returned when the broadcast was created

Minimum string length: 1
Example:

"00000000-0000-0000-0000-000000000000"

Response

The status of the broadcast with its per-chat logs

Aggregate delivery status of a broadcast — chat and recipient counts, delivery/read percentages, scheduling info and the per-chat delivery logs.

broadcast_id
string

Unique id of the broadcast (a UUID)

Example:

"00000000-0000-0000-0000-000000000000"

org_id
string<uuid>

Id of the organization that owns the broadcast

Example:

"00000000-0000-0000-0000-000000000000"

message_payload
any

The message content and metadata the broadcast was created with. null when not recorded.

Example:
created_at
string

When the broadcast was created, as an ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

broadcast_status
enum<string>

Current status of the broadcast: one of inprogress, completed, stopped, expired. null when the status has not been set yet.

Available options:
inprogress,
completed,
stopped,
expired
Example:

"completed"

total_chats
integer

Total number of chats targeted by the broadcast. null when the broadcast has no target chat list.

Example:

25

sent_chats
integer

Number of chats the broadcast was successfully sent to

Example:

22

failed_chats
integer

Number of chats where the broadcast failed to send

Example:

1

pending_chats
integer

Number of chats where the broadcast is queued but not yet sent

Example:

2

total_delivered_count
number

Total number of recipients the broadcast was delivered to, across all chats. null while no delivery info has been received.

Example:

180

total_read_count
number

Total number of recipients that read the broadcast, across all chats. null while no read info has been received.

Example:

120

total_member_count
number

Total number of members across all targeted chats — the denominator for the percentages. null when no per-chat member counts exist yet.

Example:

200

delivered_percentage
integer

Percentage of members the broadcast was delivered to, as an integer 0-100. 0 when no member counts are available.

Required range: 0 <= x <= 100
Example:

90

read_percentage
integer

Percentage of members that read the broadcast, as an integer 0-100. 0 when no member counts are available.

Required range: 0 <= x <= 100
Example:

60

performed_by
string

Who initiated the broadcast: the member's email, or "api" when initiated via the API. null for scheduled broadcasts that have not run yet.

Example:

"api"

performed_at
string

When the broadcast was executed, as an ISO 8601 timestamp. null while it has not run yet.

Example:

"2026-01-15T09:31:00.000Z"

scheduled_at
string

When the broadcast is scheduled to run, as an ISO 8601 timestamp. null for broadcasts sent immediately.

Example:

null

due_at
string

When the broadcast ran or is due to run: performed_at when executed, otherwise scheduled_at, otherwise created_at. ISO 8601 timestamp.

Example:

"2026-01-15T09:31:00.000Z"

retry_count
integer

How many times the broadcast has been retried

Example:

0

previous_retries
any

Details of previous retry runs of the broadcast. null when it has never been retried.

Example:

null

parent_broadcast_id
string

broadcast_id of the original broadcast when this broadcast is a retry or a repeat occurrence. null otherwise.

Example:

null

repeat_config
any

Repeat configuration when the broadcast is recurring. null for one-off broadcasts.

Example:

null

is_active
boolean

Whether the recurring schedule is active. null for one-off broadcasts.

Example:

null

next_occurrence_at
string

When the next occurrence of a recurring broadcast will run, as an ISO 8601 timestamp. null for one-off broadcasts.

Example:

null

occurrence_count
integer

How many occurrences of a recurring broadcast have run. null for one-off broadcasts.

Example:

null

logs
object[]

Per-chat delivery log — one entry for every chat targeted by the broadcast