> ## 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.
# Fetch Queue Jobs
> Lists the jobs in the send queue of the phone — scheduled, waiting, in flight, completed or failed.
**Deprecated.** Use [`POST /message/queues`](/api-reference/message/list-queue-jobs) instead.
Pass `queue_id` or `broadcast_id` in the request body to filter
## OpenAPI
````yaml api-reference/openapi-generated.json GET /v1/queue/jobs
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/jobs:
get:
tags:
- Queue
summary: List message queue jobs
description: >-
Lists the jobs in the send queue of the phone — scheduled, waiting, in
flight, completed or failed.
operationId: getQueueJobs
parameters:
- schema:
type: string
minLength: 1
description: >-
Only return the jobs belonging to this broadcast. Omit to return
the jobs of the whole queue.
example: 00000000-0000-0000-0000-000000000000
required: false
description: >-
Only return the jobs belonging to this broadcast. Omit to return the
jobs of the whole queue.
name: broadcast_id
in: query
- schema:
type: string
minLength: 1
description: >-
Only return the job with this queue job id (the id field of a
queue job). An id that matches nothing returns an empty array.
example: 00000000-0000-0000-0000-000000000000
required: false
description: >-
Only return the job with this queue job id (the id field of a queue
job). An id that matches nothing returns an empty array.
name: queue_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 matching queue jobs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/QueueJob'
description: >-
The matching queue jobs, or an empty array when no job matches
the filters
examples:
default:
summary: Response body
value:
- data:
chat_id: 120363000000000000@g.us
body: Hello from Periskope!
message_type: chat
quoted_message_id: ''
unique_id: 00000000-0000-0000-0000-000000000000
performed_by: api
id: 00000000-0000-0000-0000-000000000000
message_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
status: completed
stacktrace:
- 'Error: Evaluation failed: t'
attemptsStarted: 1
attemptsMade: 1
addedTimestamp: 1737373507280
finishedTimestamp: 1737373510691
processedTimestamp: 1737373507380
'400':
description: The phone server is disconnected or not reachable
content:
application/json:
examples:
error:
summary: The phone server is disconnected or not reachable
value:
code: ERROR
message: The phone server is disconnected or not reachable
status: 400
schema:
type: object
properties:
code:
type: string
example: ERROR
message:
type: string
example: The phone server is disconnected or not reachable
status:
type: integer
example: 400
example:
code: ERROR
message: The phone server is disconnected or not reachable
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.getQueueJobs();
console.log(response);
}
main();
- lang: bash
label: cURL
source: |-
curl -X GET 'https://api.periskope.app/v1/queue/jobs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210'
components:
schemas:
QueueJob:
type: object
properties:
data:
type: object
properties:
chat_id:
type: string
description: >-
Chat the message is addressed to — @c.us
for 1-1 chats, @g.us for group chats
example: 120363000000000000@g.us
body:
type: string
description: Text content of the message being sent
example: Hello from Periskope!
message_type:
type: string
description: >-
Content type of the message (e.g. 'chat' for text,
'poll_creation' for polls). Absent for some job types.
example: chat
quoted_message_id:
type: string
description: >-
message_id of the message being replied to. An empty string when
the message is not a reply.
example: ''
unique_id:
type: string
description: >-
Client-supplied unique id of the send request, when one was
provided
example: 00000000-0000-0000-0000-000000000000
performed_by:
type: string
description: >-
Who queued the message: the member's email, or "api" when queued
via the API
example: api
description: >-
The original send payload the job was queued with. Its exact keys
depend on the message type — media, poll and broadcast jobs carry
additional fields.
id:
type: string
description: >-
Unique id of the queue job (a UUID). Use it as the queue_id filter
on GET /queue/jobs or to purge the job via DELETE /queue/purge.
example: 00000000-0000-0000-0000-000000000000
message_id:
type: string
description: >-
WhatsApp message id produced when the job completed. Absent or null
while the job has not been submitted yet.
example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
status:
type: string
description: >-
Queue state of the job: one of waiting, active, completed, failed,
delayed. Absent when the queue does not report a state for the job.
example: completed
stacktrace:
type: array
items:
type: string
description: >-
Present only when the job has a failure stack trace — a
single-element array containing the first line of the most recent
stack trace.
example:
- 'Error: Evaluation failed: t'
attemptsStarted:
type: integer
description: Number of processing attempts started for the job
example: 1
attemptsMade:
type: integer
description: Number of processing attempts completed for the job
example: 1
addedTimestamp:
type: integer
description: >-
When the job was added to the queue, as an epoch timestamp in
milliseconds
example: 1737373507280
finishedTimestamp:
type: integer
description: >-
When the job finished (completed or failed), as an epoch timestamp
in milliseconds. Absent while the job is still queued or processing.
example: 1737373510691
processedTimestamp:
type: integer
description: >-
When processing of the job started, as an epoch timestamp in
milliseconds. Absent while the job is still waiting.
example: 1737373507380
description: >-
A job in the message send queue of a phone — one outgoing message
(standalone or part of a broadcast) waiting to be, or already, submitted
to WhatsApp.
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.