> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get call status

> Retrieve the current status of an outbound call

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

<Warning>
  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.
</Warning>

## Request

### Path parameters

<ParamField path="call_sid" type="string" required>
  The unique call identifier returned from the trigger endpoint (prefixed with `OUT-`).
</ParamField>

### Headers

<ParamField header="X-PolyAi-Auth-Token" type="string" required>
  Authentication token provided by your PolyAI representative
</ParamField>

## Response

<ResponseField name="status" type="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
</ResponseField>

<ResponseField name="reason" type="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.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  call_sid = "OUT-550e8400-e29b-41d4-a716-446655440000"

  url = f"https://api.us-1.platform.polyai.app/v1/outbound-calling/{call_sid}/status"
  headers = {
      "X-PolyAi-Auth-Token": "YOUR_AUTH_TOKEN"
  }

  response = requests.get(url, headers=headers)
  status_data = response.json()
  print(f"Call status: {status_data['status']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const call_sid = 'OUT-550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.us-1.platform.polyai.app/v1/outbound-calling/${call_sid}/status`,
    {
      headers: {
        'X-PolyAi-Auth-Token': 'YOUR_AUTH_TOKEN'
      }
    }
  );

  const data = await response.json();
  console.log('Call status:', data.status);
  ```
</CodeGroup>

## Response example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "success",
  "reason": ""
}
```

Failure example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "failure",
  "reason": "call queueing: max timeout limit exceeded"
}
```

## Error responses

<ResponseField name="400 Bad Request">
  Invalid call SID format.
</ResponseField>

<ResponseField name="401 Unauthorized">
  Invalid or missing authentication token.
</ResponseField>

<ResponseField name="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)
</ResponseField>

<ResponseField name="500 Internal Server Error">
  Failed to retrieve call status. Retry with exponential backoff.
</ResponseField>

## 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.