Skip to main content
GET
/
outbound
/
status
/
{call_sid}
Get call status
curl --request GET \
  --url https://api.example.com/outbound/status/{call_sid} \
  --header 'X-PolyAi-Auth-Token: <x-polyai-auth-token>'
{
  "status": "<string>",
  "reason": "<string>"
}
Retrieves the current status and reason for an outbound call. Use this endpoint to monitor call progress after triggering a call.

​
Request

​
Path parameters

​
call_sid
string
required
The unique call identifier returned from the trigger endpoint (starts with OUT-)

​
Headers

​
X-PolyAi-Auth-Token
string
required
Connector authentication token for outbound calls

​
Response

​
status
string
Current status of the call. Possible values:
  • queued - Call is queued for processing
  • ringing - Call is ringing at the destination
  • in-progress - Call is active and connected
  • completed - Call ended successfully
  • failed - Call failed to connect
  • no-answer - Call was not answered
  • busy - Destination was busy
  • cancelled - Call was cancelled before connection
​
reason
string
Additional context about the call status (may be empty for some statuses)

​
Example

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

​
Response example

{
  "status": "completed",
  "reason": "call ended normally"
}

​
Error responses

​
400 Bad Request
Invalid call SID format.
​
401 Unauthorized
Invalid or missing authentication token.
​
404 Not Found
Call SID not found. The call may not exist or may have been triggered with a different connector.
​
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 ringing phases
  • Reduce polling frequency to every 10-30 seconds once in-progress
  • Stop polling once status reaches a terminal state (completed, failed, no-answer, busy, cancelled)
  • Implement exponential backoff if you receive errors

​
Notes

  • Call status is updated in real-time as the call progresses
  • The reason field provides additional context but may be empty for some statuses
  • Terminal statuses (completed, failed, etc.) are final and will not change
  • Call status data is retained for 30 days after the call ends