> ## 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 Message Status > Tracks a message sent via POST /message/send by its unique_id: queued, scheduled, sending or failed while queued, then sent, delivered, read or played. ## OpenAPI ````yaml api-reference/openapi-generated.json GET /v1/message/{unique_id}/status 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/message/{unique_id}/status: get: tags: - Messages summary: Get the status of a queued message description: >- Tracks a message sent via POST /message/send by its unique_id: queued, scheduled, sending or failed while queued, then sent, delivered, read or played. operationId: getMessageStatus parameters: - schema: type: string minLength: 1 description: >- The unique_id of the queued message, returned by POST /message/send example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA required: true description: The unique_id of the queued message, returned by POST /message/send name: unique_id in: path - schema: type: string example: '919876543210' description: >- Optional. Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to let the API select an eligible phone automatically — within the token's phone scopes and connected; chat actions use a phone that has the chat (a group admin where required), message actions use the phone the message belongs to. required: false description: >- Optional. Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to let the API select an eligible phone automatically — within the token's phone scopes and connected; chat actions use a phone that has the chat (a group admin where required), message actions use the phone the message belongs to. name: x-phone in: header responses: '200': description: The queue job with delivery status content: application/json: schema: $ref: '#/components/schemas/MessageQueueJobStatus' examples: default: summary: Response body value: queue_id: 00000000-0000-0000-0000-000000000000 unique_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA message_id: >- true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA chat_id: 911111111111@c.us performed_by: api status: delivered status_description: Delivered to recipient. message: body: Hello World type: chat quoted_message_id: null timeline: queued_at: '2026-01-15T09:30:00.000Z' sent_at: '2026-01-15T09:30:02.000Z' failed_at: null processing_started_at: null attempts: 1 ack: 3 delivered_count: 1 read_count: 1 '400': description: The phone is off or its server is unreachable content: application/json: examples: error: summary: The phone is off or its server is unreachable value: code: ERROR message: The phone is off or its server is unreachable status: 400 schema: type: object properties: code: type: string example: ERROR message: type: string example: The phone is off or its server is unreachable status: type: integer example: 400 example: code: ERROR message: The phone is off or its server is unreachable 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 '404': description: No job in the send queue matches unique_id content: application/json: examples: error: summary: No job in the send queue matches unique_id value: code: NOT_FOUND_ERROR message: No job in the send queue matches unique_id status: 404 schema: type: object properties: code: type: string example: NOT_FOUND_ERROR message: type: string example: No job in the send queue matches unique_id status: type: integer example: 404 example: code: NOT_FOUND_ERROR message: No job in the send queue matches unique_id status: 404 '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.messages.getMessageStatus({ unique_id: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA', }); console.log(response); } main(); - lang: bash label: cURL source: >- curl -X GET 'https://api.periskope.app/v1/message/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/status' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'x-phone: 919876543210' components: schemas: MessageQueueJobStatus: allOf: - $ref: '#/components/schemas/MessageQueueJob' - type: object properties: ack: type: integer description: >- Raw delivery acknowledgement level: -1 failed, 0 pending, 1 sent, 2/3 delivered, 4 read, 5 played. null while the message record has no acknowledgement yet. example: 3 delivered_count: type: integer description: >- Number of recipients the message was delivered to. Present only once at least one recipient received or read it. example: 1 read_count: type: integer description: >- Number of recipients who read the message. Present only once at least one recipient received or read it. example: 1 description: >- A message queue job enriched with the delivery acknowledgement of the resulting message MessageQueueJob: type: object properties: queue_id: type: string description: Id of the queue job example: 00000000-0000-0000-0000-000000000000 unique_id: type: string description: >- unique_id of the queued message — the value returned by POST /message/send example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA message_id: type: string description: >- WhatsApp message_id assigned once the message was submitted. null while the job has not completed. example: true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA chat_id: type: string description: Chat the message is being sent to example: 911111111111@c.us performed_by: type: string description: >- Who queued the message: a member's email, or 'api' when queued via the API example: api status: type: string description: >- Current state of the job: one of queued, scheduled, sending, sent, pending, delivered, read, played, failed. Queue states (queued, scheduled, sending, failed) come from the send queue; once the job completed, the state reflects the delivery acknowledgement (sent, delivered, read, played — or pending/failed). example: delivered status_description: type: string description: Human-readable explanation of the status example: Delivered to recipient. message: type: object properties: body: type: string description: Text content (or caption) of the queued message example: Hello World type: type: string description: Message type of the queued message (e.g. 'chat', 'image') example: chat quoted_message_id: type: string description: >- message_id being replied to. Present only when the queued message is a reply. description: The content of the queued message timeline: type: object properties: queued_at: type: string description: When the job was added to the queue (ISO 8601) example: '2026-01-15T09:30:00.000Z' sent_at: type: string description: >- When the job finished successfully (ISO 8601). Present only for completed jobs. example: '2026-01-15T09:30:02.000Z' failed_at: type: string description: When the job failed (ISO 8601). Present only for failed jobs. processing_started_at: type: string description: >- When the job started being processed (ISO 8601). Present only for jobs currently being submitted. description: Timestamps of the job lifecycle attempts: type: integer description: Number of submission attempts made so far example: 1 description: >- A job in the message send queue of a phone. Every message sent via the API passes through this queue. 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.