Get call status

Retrieve the current status of an outbound call

GET /v1/outbound-calling/{call_sid}/status

Get call status

cURL

curl --request GET \
  --url https://api.example.com/v1/outbound-calling/{call_sid}/status \
  --header 'X-PolyAi-Auth-Token: <x-polyai-auth-token>'

200

{
  "status": "<string>",
  "reason": "<string>"
}

Retrieves the current status for an outbound call. Use this endpoint to monitor call progress after triggering a call.

Call status data is retained for approximately 2 hours after the call ends. After this period, the endpoint will return a 404 Not Found error.

Request

Path parameters

call_sid · string · required

The unique call identifier returned from the trigger endpoint (prefixed with OUT-).

Headers

X-PolyAi-Auth-Token · string · required

Authentication token provided by your PolyAI representative

Response

status · string

Current status of the call. One of:

• queued – Call has been queued for processing
• calling – Call is being placed to the destination
• success – Call completed successfully
• failure – Call failed to connect or was not answered

reason · string

Human-readable reason for the current status. Typically populated for terminal failure states (e.g., "call queueing: max timeout limit exceeded"); otherwise an empty string.

Example

cURL

curl -X GET "https://api.us-1.platform.polyai.app/v1/outbound-calling/OUT-550e8400-e29b-41d4-a716-446655440000/status" \
  -H "X-PolyAi-Auth-Token: YOUR_AUTH_TOKEN"

Response example

{
  "status": "success",
  "reason": ""
}

Failure example:

{
  "status": "failure",
  "reason": "call queueing: max timeout limit exceeded"
}

Error responses

400 Bad Request

Invalid call SID format.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Call SID not found. This may occur if:

• The call does not exist
• More than 2 hours have passed since the call ended (status data expired)

500 Internal Server Error

Failed to retrieve call status. Retry with exponential backoff.

Polling recommendations

When monitoring call status:

• Poll every 2-5 seconds during the queued and calling phases
• Stop polling once status reaches a terminal state (success or failure)
• Implement exponential backoff if you receive errors
• Store the final status before the 2-hour retention window expires if you need long-term records

Notes

• Call status is updated in real-time as the call progresses.
• Terminal statuses (success, failure) are final and will not change.
• The reason field is typically populated only for failure states – successful and in-progress calls return an empty string.
• Status data is retained for approximately 2 hours after the call ends – poll and store data if you need longer retention.