List Calls

GET /api/calls

List Calls

cURL

curl --request GET \
  --url https://api.example.com/api/calls

Response

{
  "success": true,
  "data": [
    {
      "call_sid": "call_abc123def456",
      "to_number": "[phone]",
      "from_number": "[phone]",
      "agent_id": "agent_xyz789",
      "agent_name": "Sales Rep",
      "client_id": "org_123",
      "call_type": "outbound",
      "status": "completed",
      "recording_enabled": true,
      "total_cost": 12.35,
      "duration_seconds": 120.5,
      "turn_count": 7,
      "created_at": "2026-03-09T10:00:00Z",
      "updated_at": "2026-03-09T10:02:30Z",
      "start_time": "2026-03-09T10:00:05Z",
      "end_time": "2026-03-09T10:02:25Z",
      "end_reason": "tool_end_call",
      "billing_status": "billed"
    }
  ],
  "pagination": {
    "next_cursor": "eyJjYWxsX3NpZCI6ICJjYWxsX2FiYzEyMyJ9",
    "has_more": true,
    "page_size": 50
  }
}

Retrieve a paginated list of calls for your organization.

Query Parameters

limit · integer · default: "50"

Maximum number of calls to return (1-100).

cursor · string

Base64-encoded cursor from previous response for pagination. Omit for first page.

Response

success · boolean

Indicates if the request was successful.

data · array

List of call summary objects.

pagination · object

Pagination metadata.

• next_cursor: Cursor for fetching next page
• has_more: Boolean indicating if more results exist
• page_size: Number of results in current page

Call Summary Fields

call_sid · string · required

Unique call identifier (format: call_ prefix + alphanumeric).

to_number · string · required

Phone number that was called (E.164 format).

from_number · string

Caller phone number (E.164 format).

agent_id · string · required

ID of the agent that handled the call.

agent_name · string

Name of the agent.

call_type · string

Type of call: inbound, outbound, or preview.

status · string

Current call status (e.g., completed, ringing, in_progress).

recording_enabled · boolean

Whether recording was enabled for this call.

total_cost · number

Total cost in credits.

duration_seconds · number

Call duration in seconds.

turn_count · number

Number of conversation turns.

created_at · string

ISO8601 timestamp when the call was created.

end_reason · string

Reason why the call ended (e.g., tool_end_call, user_hangup).

Response

{
  "success": true,
  "data": [
    {
      "call_sid": "call_abc123def456",
      "to_number": "[phone]",
      "from_number": "[phone]",
      "agent_id": "agent_xyz789",
      "agent_name": "Sales Rep",
      "client_id": "org_123",
      "call_type": "outbound",
      "status": "completed",
      "recording_enabled": true,
      "total_cost": 12.35,
      "duration_seconds": 120.5,
      "turn_count": 7,
      "created_at": "2026-03-09T10:00:00Z",
      "updated_at": "2026-03-09T10:02:30Z",
      "start_time": "2026-03-09T10:00:05Z",
      "end_time": "2026-03-09T10:02:25Z",
      "end_reason": "tool_end_call",
      "billing_status": "billed"
    }
  ],
  "pagination": {
    "next_cursor": "eyJjYWxsX3NpZCI6ICJjYWxsX2FiYzEyMyJ9",
    "has_more": true,
    "page_size": 50
  }
}

This endpoint uses cursor-based pagination. Use the next_cursor from the response to fetch subsequent pages. Omit the cursor parameter for the first page.