GET — Get Leg Details

15 min

Description

Fetches the current details of a Leg using its leg_sid. This is useful to:

Check the leg state (created / ringing / connected / terminal)

Fetch timestamps (created / start / end)

Pull additional runtime statuses (bridge / recording / play / gather / hold, etc.) via fields

Endpoint

GET

/v2/accounts/{account_sid}/legs/{leg_sid}

Full URL

https://cpaas-api.in.exotel.com/v2/accounts/{account_sid}/legs/{leg_sid}

Authentication

Type: HTTP Basic Authentication

Username: API Key

Password: API Token

Request Headers

Content-Type: application/json Authorization: Basic <base64(API_KEY:API_TOKEN)>

Path Parameters

Parameter	Type	Required	Description
account_sid	string	Yes	Exotel Account SID (from Exotel dashboard)
leg_sid	string	Yes	Leg SID returned by Create a Leg

Query Parameters (Optional)

fields

Use fields to request additional runtime statuses in the response.

Type: comma-separated string

Example

fields=bridge_status,recording_status,tx_audio_status,rx_audio_status,hold_status,gather_status,play_status

Field	Description
bridge_status	Whether the leg is bridged or not
recording_status	Whether recording is active
tx_audio_status	Transmit audio status (muted/normal)
rx_audio_status	Receive audio status (muted/normal)
hold_status	Whether leg is on hold
gather_status	Whether DTMF gather is active
play_status	Whether audio playback is active

Tip: If you don’t pass fields, the API returns the standard leg object without the additional_info section.

Example Request

Basic request

curl -u "<API_KEY>:<API_TOKEN>" \ -X GET \ https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>

Request with fields

curl -u "<API_KEY>:<API_TOKEN>" \ -X GET \ "https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>?fields=bridge_status,recording_status,hold_status,gather_status,play_status"

Success Response

HTTP 200 – OK

{ "request_id": "ce7b872225b348f09e80115c1ff569a3", "method": "GET", "http_code": 200, "response": { "error_data": null, "data": { "leg_sid": "2QYATxQ9t4UKcUwcqJClSa9OEZ400000", "account_sid": "ameyo5m", "contact_uri": "09163816621", "exophone": "08030752400", "caller_id": "8030752501", "direction": "outbound", "network_type": "pstn", "time_limit": 600, "state": "connected", "date_created": "2026-01-19T08:02:32Z", "date_updated": "2026-01-19T08:03:06Z", "start_time": "2026-01-19T08:02:35Z", "additional_info": { "recording_status": "not_recording", "hold_status": "normal", "gather_status": "not_gathering", "play_status": "not_playing", "bridge_status": "not_bridged" } } } }

Response Fields

Core Fields

Field	Description
leg_sid	Unique identifier for the leg
account_sid	Exotel account identifier
contact_uri	Destination of the leg (phone/SIP URI)
exophone	Caller ID / Exotel number used
caller_id	Resolved caller ID presented
direction	inbound or outbound
network_type	pstn or voip
time_limit	Max time allowed for the leg
state	Current leg state (example: connected, terminal)
date_created	When leg was created
date_updated	Last update time
start_time	When leg connected/started (if applicable)

additional_info (only if fields requested)

Field	Description
recording_status	Recording status
hold_status	Hold status
gather_status	DTMF gather status
play_status	Playback status
bridge_status	Bridge connection status
tx_audio_status	Transmit audio status (if requested)
rx_audio_status	Receive audio status (if requested)

Error Responses

HTTP Code	Meaning	Description
400	Bad Request	Invalid fields value or malformed request
401	Unauthorized	Invalid API Key / Token
403	Forbidden	Access not allowed for this account
404	Not Found	Leg SID not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error

Notes & Best Practices

Use Get Leg Details for polling only when needed — prefer events for real-time status

Always log request_id for debugging

If you need runtime action statuses (play/record/bridge/hold), always pass fields