Skip to main content
GET
/
calls
/
{id}
Get a call
curl --request GET \
  --url https://api.dialnexa.com/v1/calls/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "call_abc123",
  "agent_id": "agt_abc123",
  "agent_version_number": 1,
  "to_phone_number": "+919876543210",
  "from_phone_number": "+912234567890",
  "status": "completed",
  "duration_seconds": 145,
  "recording_url": "https://recordings.dialnexa.com/call_abc123.mp3",
  "metadata": {
    "customer_name": "Priya Sharma",
    "account_id": "ACC-9912"
  },
  "created_at": "2024-03-01T10:00:00.000Z",
  "ended_at": "2024-03-01T10:02:25.000Z"
}
Fetches the complete record for a single call by call_id. The response includes the call’s current status, the destination and source numbers, the assigned agent_id, timestamps for when the call was placed and when it ended, and, once the call reaches a terminal state, the duration, recording URL, and transcript. Use this endpoint to poll for completion after triggering a call, render a call detail page, or sync per-call data into a downstream system.

​
When to use this

  • Synchronous workflows: trigger a call and poll until it reaches a terminal status before continuing.
  • Operational dashboards: render a call detail view with status, duration, and the linked agent.
  • CRM sync: write back the call outcome to the customer record the call was made for.

​
Polling vs. webhooks

For production traffic, webhooks are the preferred way to know when a call has ended, they avoid the request volume and latency of repeated polling. Subscribe to call.completed and call.failed via Create Webhook and use this endpoint only when you specifically need to fetch the latest state on demand (for example, a user opens a call detail page). When polling is required, the call’s status transitions from initiated to in-progress, then to one of completed, failed, busy, or no-answer. Poll every 5 to 10 seconds with an exponential cap; do not poll faster than once per second.

​
Path parameters

ParameterDescription
idThe call ID, for example call_x9y3zp4mq7r1.

​
Errors

  • 404 Not Found is returned when the call does not exist.
  • 403 Forbidden is returned when the API key cannot read calls on this workspace.

​
Request

curl "https://api.dialnexa.com/v1/calls/call_x9y3zp4mq7r1" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "id": "call_x9y3zp4mq7r1",
  "status": "completed",
  "agent_id": "agt_k7m2nq9xw4p8",
  "to_phone_number": "+919876543210",
  "from_phone_number": "+912234567890",
  "duration_sec": 142,
  "created_at": "2024-05-01T14:22:00.000Z",
  "ended_at": "2024-05-01T14:24:22.000Z"
}

Authorizations

​
Authorization
string
header
required

Pass your API key as a Bearer token in the Authorization header.

Path Parameters

​
id
string
required

Response

Success.

​
id
string
Example:

"call_abc123"

​
agent_id
string
Example:

"agt_abc123"

​
agent_version_number
integer
Example:

1

​
to_phone_number
string
Example:

"+919876543210"

​
from_phone_number
string
Example:

"+912234567890"

​
status
enum<string>

Canonical call status. Use with end_reason for final outcome review.

Available options:
created,
initiated,
sent,
received,
completed,
did_not_pick,
busy,
no_answer,
failed,
cancelled,
retry_expired
Example:

"completed"

​
duration_seconds
integer
Example:

145

​
recording_url
string | null
Example:

"https://recordings.dialnexa.com/call_abc123.mp3"

​
metadata
object
Example:
{
  "customer_name": "Priya Sharma",
  "account_id": "ACC-9912"
}
​
created_at
string<date-time>
Example:

"2024-03-01T10:00:00.000Z"

​
ended_at
string<date-time>
Example:

"2024-03-01T10:02:25.000Z"