Skip to main content
POST
/
v1
/
list-calls
curl -X POST https://api.voicy.co/v1/list-calls \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filter_criteria": {
      "call_status": ["user_hangup", "agent_hangup"]
    },
    "sort_order": "descending",
    "limit": 10
  }'

[
  {
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "call_type": "phone_call",
    "call_status": "user_hangup",
    "agent": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Customer Support Agent",
      "version": 2
    },
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440099",
      "name": "Acme Corp"
    },
    "from_number": "+15551234567",
    "to_number": "+15559876543",
    "direction": "outgoing",
    "start_timestamp": 1704067200000,
    "duration_ms": 120000,
    "call_cost": {
      "combined_cost": 0.056,
      "currency": "usd"
    }
  },
  {
    "call_id": "550e8400-e29b-41d4-a716-446655440002",
    "call_type": "phone_call",
    "call_status": "agent_hangup",
    "agent": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Customer Support Agent",
      "version": 1
    },
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440099",
      "name": "Acme Corp"
    },
    "from_number": "+15559876543",
    "to_number": "+15551234567",
    "direction": "incoming",
    "start_timestamp": 1704063600000,
    "duration_ms": 180000,
    "call_cost": null
  }
]
Retrieve a list of calls with optional filtering by status, agent, direction, and time range.
This endpoint uses POST to support complex filter criteria in the request body.

​
Request Body

​
filter_criteria
object
Optional filters to apply.
​
sort_order
string
default:"descending"
Sort order: ascending or descending (by start time).
​
limit
integer
default:"50"
Maximum number of results (1-1000).
​
pagination_key
string
Cursor for pagination. Use the last call_id from the previous page.

​
Response

Returns an array of lightweight call objects. These include core metadata (status, agent, timing, cost) but omit transcript, summary, recording_url, detected_gender, vars_provided, and vars_extracted for performance. Use Get Call to retrieve the full call object. 
curl -X POST https://api.voicy.co/v1/list-calls \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filter_criteria": {
      "call_status": ["user_hangup", "agent_hangup"]
    },
    "sort_order": "descending",
    "limit": 10
  }'

[
  {
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "call_type": "phone_call",
    "call_status": "user_hangup",
    "agent": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Customer Support Agent",
      "version": 2
    },
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440099",
      "name": "Acme Corp"
    },
    "from_number": "+15551234567",
    "to_number": "+15559876543",
    "direction": "outgoing",
    "start_timestamp": 1704067200000,
    "duration_ms": 120000,
    "call_cost": {
      "combined_cost": 0.056,
      "currency": "usd"
    }
  },
  {
    "call_id": "550e8400-e29b-41d4-a716-446655440002",
    "call_type": "phone_call",
    "call_status": "agent_hangup",
    "agent": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Customer Support Agent",
      "version": 1
    },
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440099",
      "name": "Acme Corp"
    },
    "from_number": "+15559876543",
    "to_number": "+15551234567",
    "direction": "incoming",
    "start_timestamp": 1704063600000,
    "duration_ms": 180000,
    "call_cost": null
  }
]