Call Status
Read the live state and details of a call with GET /v1/calls/{call_id}, and the states a call moves through.
Showing instructions for Xebit VoiceCloud.Showing instructions for Xebit VoiceKit, on your own infrastructure. Switch with the selector at the top. Updated 22 October 2026.
Read where a call is and what has happened on it with GET /v1/calls/{call_id}. For high volumes, let outbound webhooks tell you instead of polling.
Get a call
/v1/calls/{call_id}Requires the calls:read scope.
curl -s "https://api.voice.xebit.ai/v1/calls/call_abc123" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "call_abc123"
response = requests.get(
f"{BASE_URL}/calls/{call_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "call_abc123";
const response = await fetch(`${BASE_URL}/calls/${callId}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s "https://<your-xebit-voicekit-host>/v1/calls/call_abc123" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "call_abc123"
response = requests.get(
f"{BASE_URL}/calls/{call_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "call_abc123";
const response = await fetch(`${BASE_URL}/calls/${callId}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Sample response:
{
"data": {
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "in_progress",
"agent_id": "agent_123",
"contact_number": "+919876543210",
"contact_name": "Raj Patel",
"contact_email": "raj@company.com",
"additional_info": {
"company": "Acme Corp"
},
"scheduled_at": "2024-01-27T03:02:00.000Z",
"completed_at": null,
"error": null,
"created_at": "2024-01-27T03:00:00.000Z",
"updated_at": "2024-01-27T03:00:00.000Z"
}
}Response fields
| Field | Description |
|---|---|
call_id | Unique identifier of the call. |
status | Where the call is in its lifecycle. See the states below. |
agent_id | The agent assigned to the call. |
contact_number | Destination number in E.164 format. |
contact_name | Contact name, if one was given when the call was created. |
contact_email | Contact email, if one was given when the call was created. |
additional_info | The custom key-value pairs sent at creation. |
scheduled_at | When the call was scheduled to start. |
completed_at | When the call ended, or null if it has not. |
error | Error details when the call failed, otherwise null. |
created_at / updated_at | When the record was created and last changed. |
Call states
Every call moves through a fixed set of states. Use them to drive your own business logic.
| State | Meaning |
|---|---|
initiated | The request has been accepted and is waiting to be handed to your carrier trunk. |
ringing | The destination phone is ringing. |
in_progress | The agent and the person are talking. |
completed | The conversation finished normally. |
failed | The call could not be completed, for example a busy line or an invalid number. |
cancelled | Your system stopped the call before it was answered. |
On Xebit VoiceCloud, every request to this endpoint counts toward your rate limit, so prefer webhooks to tight polling loops.
On Xebit VoiceKit, polling load lands on your own infrastructure and counts toward the rate limits your deployment is configured with, so prefer webhooks to tight polling loops.
For high volume integrations, subscribe to outbound webhooks to receive state changes as they happen. Use Cases shows typical set-ups.