Retrieve a Live Call

Get real-time information about a currently active call, including call state and live metrics.

This endpoint retrieves detailed information about an in-progress call. Unlike the standard Retrieve a Call endpoint which returns finalized CDRs, this endpoint provides real-time status for active calls including current state, call flow position, and live duration metrics.

Note: This endpoint only returns data for calls that are currently in progress. For completed calls, use the Retrieve a Call endpoint instead.

Use Case: Monitor active calls in real-time, implement live dashboards, or check call status before performing operations like transfer or hangup.

HTTP Request

GEThttps://api.vobiz.ai/api/v1/account/{auth_id}/call/{callUuid}/?status=live

Path Parameters

auth_idstringRequired

Your Vobiz account ID

callUuidstringRequired

Unique identifier of the live call to retrieve

Query Parameters

Request Parameters

Parameter	Type	Description
`status`required	string	Must be set to "live" to retrieve real-time call information.

Important: The status=live query parameter is required. Without it, the endpoint will return the finalized CDR (if the call has ended) or a 404 error (if the call UUID doesn't exist).

Response

Returns live call information including current status, call legs, and real-time metrics.

Response - 200 OK

{
  "api_id": "c8b427f6-58ce-11e1-86da-adf28403fe48",
  "calls": [
    {
      "answer_time": "2014-10-15 09:03:43",
      "bill_duration": null,
      "billed_duration": null,
      "call_direction": "outbound",
      "call_duration": 180,
      "call_state": "ACTIVE",
      "call_uuid": "97ceeb52-58b6-11e1-86da-77300b68f8bb", // Also referred to as request_uuid
      "conference_uuid": null,
      "end_time": null,
      "from_number": "+14156667777",
      "initiation_time": "2014-10-15 09:03:38",
      "parent_call_uuid": null,
      "hangup_cause_code": null,
      "hangup_cause_name": null,
      "hangup_source": null,
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Call/97ceeb52-58b6-11e1-86da-77300b68f8bb/",
      "to_number": "+14156667778",
      "total_amount": null,
      "total_rate": null,
      "stir_verification": "verified",
      "stir_attestation": "A",
      "source_ip": "1.1.1.1"
    }
  ]
}

Live Call Specific Fields

call_state - Current state of the call (e.g., "ACTIVE", "RINGING", "EARLY")

call_duration - Live call duration in seconds since answer_time

end_time - Will be null for active calls

billed_duration - Will be null until call ends

total_amount - Will be null until call ends and billing is calculated

hangup_* - All hangup-related fields will be null for active calls

Call State Values:

RINGING - Call is ringing, not yet answered
EARLY - Early media state (e.g., ringback tone playing)
ACTIVE - Call is connected and in progress
HELD - Call is on hold

Example Request

Retrieve Live Call Status

Request

GET https://api.vobiz.ai/api/v1/account/MA2025RK4E639VJFZAGV/call/97ceeb52-58b6-11e1-86da-77300b68f8bb/?status=live

Headers:
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
Content-Type: application/json

Use Cases

•Build real-time call monitoring dashboards
•Check call state before performing transfer or hangup operations
•Monitor ongoing call duration for time-based triggers
•Verify call connectivity and troubleshoot issues in real-time
•Display live call information to supervisors or agents
•Implement call timers and duration alerts

Tip: Poll this endpoint periodically to monitor live call metrics. Use the call_duration field to calculate current call costs in real-time by multiplying with the rate from Pricing.

Error Response: If the call is not currently live or has already ended, you'll receive a 404 error. In that case, use the standard Retrieve a Call endpoint to get the finalized CDR.

Retrieve All Calls

Integrations