> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periskope.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Broadcast Status
> Returns the aggregate delivery status of a broadcast: sent, failed and pending counts, delivered/read percentages, and scheduling info.
**Deprecated.** Use [`POST /message/queues`](/api-reference/message/list-queue-jobs) with `broadcast_id` in the request body instead
## OpenAPI
````yaml api-reference/openapi-generated.json GET /v1/queue/broadcast
openapi: 3.0.3
info:
title: Periskope API
version: 1.0.0
description: >-
Periskope external API.
Responses use a flat, unwrapped shape: most endpoints return the resource at
the top level, and list endpoints return a wrapper object with pagination
inline (e.g. `{ from, to, count, chats: [...] }`). The documented response
schemas describe these shapes directly.
servers:
- url: https://api.periskope.app
security:
- bearerAuth: []
paths:
/v1/queue/broadcast:
get:
tags:
- Queue
summary: Get the status of a broadcast
description: >-
Returns the aggregate delivery status of a broadcast: sent, failed and
pending counts, delivered/read percentages, and scheduling info.
operationId: getBroadcastStatus
parameters:
- schema:
type: string
minLength: 1
description: >-
Id of the broadcast to fetch (a UUID), as returned when the
broadcast was created
example: 00000000-0000-0000-0000-000000000000
required: true
description: >-
Id of the broadcast to fetch (a UUID), as returned when the
broadcast was created
name: broadcast_id
in: query
- schema:
type: string
minLength: 1
example: '919876543210'
description: >-
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.
required: true
description: >-
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.
name: x-phone
in: header
responses:
'200':
description: The status of the broadcast with its per-chat logs
content:
application/json:
schema:
$ref: '#/components/schemas/QueueBroadcastStatus'
examples:
default:
summary: Response body
value:
broadcast_id: 00000000-0000-0000-0000-000000000000
org_id: 00000000-0000-0000-0000-000000000000
message_payload:
body: Hello from Periskope!
message_type: chat
created_at: '2026-01-15T09:30:00.000Z'
broadcast_status: completed
total_chats: 25
sent_chats: 22
failed_chats: 1
pending_chats: 2
total_delivered_count: 180
total_read_count: 120
total_member_count: 200
delivered_percentage: 90
read_percentage: 60
performed_by: api
performed_at: '2026-01-15T09:31:00.000Z'
scheduled_at: null
due_at: '2026-01-15T09:31:00.000Z'
retry_count: 0
previous_retries: null
parent_broadcast_id: null
repeat_config: null
is_active: null
next_occurrence_at: null
occurrence_count: null
logs:
- broadcast_id: 00000000-0000-0000-0000-000000000000
org_id: 00000000-0000-0000-0000-000000000000
chat_id: 120363000000000000@g.us
org_phone: 911111111111@c.us
message_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
is_success: true
remarks: null
member_count: 12
delivered_count: 10
read_count: 7
delivery_info: null
poll_results: null
created_at: '2026-01-15T09:30:00.000Z'
completed_at: '2026-01-15T09:31:00.000Z'
'400':
description: >-
Broadcast not found — no broadcast with the given broadcast_id
exists in the workspace
content:
application/json:
examples:
error:
summary: >-
Broadcast not found — no broadcast with the given
broadcast_id exists in the workspace
value:
code: ERROR
message: >-
Broadcast not found — no broadcast with the given
broadcast_id exists in the workspace
status: 400
schema:
type: object
properties:
code:
type: string
example: ERROR
message:
type: string
example: >-
Broadcast not found — no broadcast with the given
broadcast_id exists in the workspace
status:
type: integer
example: 400
example:
code: ERROR
message: >-
Broadcast not found — no broadcast with the given
broadcast_id exists in the workspace
status: 400
'401':
description: Invalid, expired or missing API token
content:
application/json:
examples:
error:
summary: Invalid, expired or missing API token
value:
code: UNAUTHORIZED_ERROR
message: Invalid bearer auth token
status: 401
schema:
type: object
properties:
code:
type: string
example: UNAUTHORIZED_ERROR
message:
type: string
example: Invalid bearer auth token
status:
type: integer
example: 401
example:
code: UNAUTHORIZED_ERROR
message: Invalid bearer auth token
status: 401
'422':
description: Request validation failed
content:
application/json:
examples:
error:
summary: Request validation failed
value:
code: VALIDATION_ERROR
message: Request validation failed
status: 422
fields:
body.chat_id:
message: chat_id is required
schema:
type: object
properties:
code:
type: string
example: VALIDATION_ERROR
message:
type: string
example: Request validation failed
status:
type: integer
example: 422
fields:
type: object
additionalProperties:
type: object
properties:
message:
type: string
value: {}
example:
body.chat_id:
message: chat_id is required
example:
code: VALIDATION_ERROR
message: Request validation failed
status: 422
fields:
body.chat_id:
message: chat_id is required
'429':
description: Rate limit exceeded
content:
application/json:
examples:
error:
summary: Rate limit exceeded
value:
code: RATE_LIMIT_ERROR
message: You can only make 100 requests per second
status: 429
schema:
type: object
properties:
code:
type: string
example: RATE_LIMIT_ERROR
message:
type: string
example: You can only make 100 requests per second
status:
type: integer
example: 429
example:
code: RATE_LIMIT_ERROR
message: You can only make 100 requests per second
status: 429
'500':
description: Internal server error
content:
application/json:
examples:
error:
summary: Internal server error
value:
code: UNKNOWN_ERROR
message: Internal server error
status: 500
schema:
type: object
properties:
code:
type: string
example: UNKNOWN_ERROR
message:
type: string
example: Internal server error
status:
type: integer
example: 500
example:
code: UNKNOWN_ERROR
message: Internal server error
status: 500
security:
- bearerAuth: []
x-codeSamples:
- lang: typescript
label: TypeScript
source: |-
import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
phone: '919876543210', // the phone to act with (x-phone)
});
async function main() {
const response = await client.queue.getBroadcastStatus({
broadcast_id: '00000000-0000-0000-0000-000000000000',
});
console.log(response);
}
main();
- lang: bash
label: cURL
source: >-
curl -X GET
'https://api.periskope.app/v1/queue/broadcast?broadcast_id=00000000-0000-0000-0000-000000000000'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210'
components:
schemas:
QueueBroadcastStatus:
type: object
properties:
broadcast_id:
type: string
description: Unique id of the broadcast (a UUID)
example: 00000000-0000-0000-0000-000000000000
org_id:
type: string
format: uuid
description: Id of the organization that owns the broadcast
example: 00000000-0000-0000-0000-000000000000
message_payload:
description: >-
The message content and metadata the broadcast was created with.
null when not recorded.
example:
body: Hello from Periskope!
message_type: chat
created_at:
type: string
description: When the broadcast was created, as an ISO 8601 timestamp
example: '2026-01-15T09:30:00.000Z'
broadcast_status:
type: string
enum:
- inprogress
- completed
- stopped
- expired
description: >-
Current status of the broadcast: one of inprogress, completed,
stopped, expired. null when the status has not been set yet.
example: completed
total_chats:
type: integer
description: >-
Total number of chats targeted by the broadcast. null when the
broadcast has no target chat list.
example: 25
sent_chats:
type: integer
description: Number of chats the broadcast was successfully sent to
example: 22
failed_chats:
type: integer
description: Number of chats where the broadcast failed to send
example: 1
pending_chats:
type: integer
description: Number of chats where the broadcast is queued but not yet sent
example: 2
total_delivered_count:
type: number
description: >-
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:
type: number
description: >-
Total number of recipients that read the broadcast, across all
chats. null while no read info has been received.
example: 120
total_member_count:
type: number
description: >-
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:
type: integer
minimum: 0
maximum: 100
description: >-
Percentage of members the broadcast was delivered to, as an integer
0-100. 0 when no member counts are available.
example: 90
read_percentage:
type: integer
minimum: 0
maximum: 100
description: >-
Percentage of members that read the broadcast, as an integer 0-100.
0 when no member counts are available.
example: 60
performed_by:
type: string
description: >-
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:
type: string
description: >-
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:
type: string
description: >-
When the broadcast is scheduled to run, as an ISO 8601 timestamp.
null for broadcasts sent immediately.
example: null
due_at:
type: string
description: >-
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:
type: integer
description: How many times the broadcast has been retried
example: 0
previous_retries:
description: >-
Details of previous retry runs of the broadcast. null when it has
never been retried.
example: null
parent_broadcast_id:
type: string
description: >-
broadcast_id of the original broadcast when this broadcast is a
retry or a repeat occurrence. null otherwise.
example: null
repeat_config:
description: >-
Repeat configuration when the broadcast is recurring. null for
one-off broadcasts.
example: null
is_active:
type: boolean
description: >-
Whether the recurring schedule is active. null for one-off
broadcasts.
example: null
next_occurrence_at:
type: string
description: >-
When the next occurrence of a recurring broadcast will run, as an
ISO 8601 timestamp. null for one-off broadcasts.
example: null
occurrence_count:
type: integer
description: >-
How many occurrences of a recurring broadcast have run. null for
one-off broadcasts.
example: null
logs:
type: array
items:
$ref: '#/components/schemas/QueueBroadcastLog'
description: >-
Per-chat delivery log — one entry for every chat targeted by the
broadcast
description: >-
Aggregate delivery status of a broadcast — chat and recipient counts,
delivery/read percentages, scheduling info and the per-chat delivery
logs.
QueueBroadcastLog:
type: object
properties:
broadcast_id:
type: string
description: Id of the broadcast the log entry belongs to
example: 00000000-0000-0000-0000-000000000000
org_id:
type: string
format: uuid
description: Id of the organization that owns the broadcast
example: 00000000-0000-0000-0000-000000000000
chat_id:
type: string
description: >-
Chat this log entry is for — @c.us for 1-1
chats, @g.us for group chats
example: 120363000000000000@g.us
org_phone:
type: string
description: >-
Org phone (WhatsApp account) the broadcast message was sent from for
this chat. null while the message has not been assigned to a phone.
example: 911111111111@c.us
message_id:
type: string
description: >-
WhatsApp message id of the sent broadcast message. null while the
message has not been sent.
example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
is_success:
type: boolean
description: >-
Whether the broadcast message was sent successfully to this chat:
true when sent, false when it failed, null while it is still
pending.
example: true
remarks:
type: string
description: >-
Failure or status remarks for this chat (e.g. why the send failed).
null when there is nothing to report.
example: null
member_count:
type: integer
description: >-
Number of members in the chat at send time — the denominator used
for delivery and read percentages. null when unknown.
example: 12
delivered_count:
type: integer
description: >-
Number of recipients in the chat the message was delivered to. null
while no delivery info has been received.
example: 10
read_count:
type: integer
description: >-
Number of recipients in the chat that read the message. null while
no read info has been received.
example: 7
delivery_info:
description: >-
Raw per-chat delivery details reported by WhatsApp, if any. null
when not available.
poll_results:
description: >-
Aggregated poll votes for this chat when the broadcast was a poll.
null otherwise.
created_at:
type: string
description: When the log entry was created, as an ISO 8601 timestamp
example: '2026-01-15T09:30:00.000Z'
completed_at:
type: string
description: >-
When the send to this chat completed, as an ISO 8601 timestamp. null
while pending.
example: '2026-01-15T09:31:00.000Z'
description: >-
Per-chat delivery log of a broadcast — one entry per chat targeted by
the broadcast.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your Periskope API token, sent as `Authorization: Bearer `.
Generate one from the Periskope dashboard under **Settings → API &
Webhooks**. API access requires an active Pro or Enterprise plan.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.