Skip to main content
POST
/
api
/
calls
curl -X POST "https://api.zudu.ai/api/calls" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \
  -d '{
    "page": 0,
    "limit": 20,
    "sort_by": "created_at",
    "sort_order": "descending",
    "filter_criteria": {
      "call_status": ["ONGOING", "ENDED"],
      "call_type": ["PHONE_CALL"],
      "agent_id": "agent_1234567890"
    }
  }'

{
  "message": "Calls retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "calls": [
      {
        "call_id": "call_abc123def456",
        "agent_id": "agent_1234567890",
        "call_status": "ENDED",
        "call_type": "PHONE_CALL",
        "from_number": "+14157774444",
        "to_number": "+12137774445",
        "direction": "OUTBOUND",
        "created_at": 1705320000000,
        "start_timestamp": 1705320010000,
        "end_timestamp": 1705320100000
      }
    ],
    "pagination": {
      "page": 0,
      "limit": 20,
      "total": 150,
      "total_pages": 8
    },
    "returned_count": 20,
    "sort_order": "descending",
    "sort_by": "created_at",
    "applied_filters": {
      "call_status": ["ONGOING", "ENDED"],
      "call_type": ["PHONE_CALL"]
    }
  }
}
Retrieve a paginated list of calls for your organization with optional filtering by status, date range, agent, and other criteria. 
curl -X POST "https://api.zudu.ai/api/calls" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \
  -d '{
    "page": 0,
    "limit": 20,
    "sort_by": "created_at",
    "sort_order": "descending",
    "filter_criteria": {
      "call_status": ["ONGOING", "ENDED"],
      "call_type": ["PHONE_CALL"],
      "agent_id": "agent_1234567890"
    }
  }'

{
  "message": "Calls retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "calls": [
      {
        "call_id": "call_abc123def456",
        "agent_id": "agent_1234567890",
        "call_status": "ENDED",
        "call_type": "PHONE_CALL",
        "from_number": "+14157774444",
        "to_number": "+12137774445",
        "direction": "OUTBOUND",
        "created_at": 1705320000000,
        "start_timestamp": 1705320010000,
        "end_timestamp": 1705320100000
      }
    ],
    "pagination": {
      "page": 0,
      "limit": 20,
      "total": 150,
      "total_pages": 8
    },
    "returned_count": 20,
    "sort_order": "descending",
    "sort_by": "created_at",
    "applied_filters": {
      "call_status": ["ONGOING", "ENDED"],
      "call_type": ["PHONE_CALL"]
    }
  }
}

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Request Body

​
page
integer
Page number (0-indexed)Default: 0Example: 0
​
limit
integer
Number of results per pageDefault: 100Example: 20
​
sort_by
string
Field to sort byOptions: created_at, updated_at, start_timestamp, end_timestamp, call_id, agent_id, call_status, call_typeDefault: created_atExample: "created_at"
​
sort_order
string
Sort orderOptions: ascending, descendingDefault: descendingExample: "descending"
​
filter_criteria
object
Filter criteria for callsSupported filters:
  • call_status: Array of statuses (REGISTERED, ONGOING, ENDED, ERROR, SCHEDULED)
  • call_type: Array of types (PHONE_CALL, WEB_CALL)
  • agent_id: Single agent ID
  • call_id: Single call ID
  • batch_call_id: Batch call ID
  • direction: Array of directions (INBOUND, OUTBOUND)
  • from_number: Source phone number
  • to_number: Destination phone number
  • start_timestamp: Object with gte (greater than or equal) and/or lte (less than or equal)
  • end_timestamp: Object with gte and/or lte
Example:
{
  "call_status": ["ONGOING", "ENDED"],
  "call_type": ["PHONE_CALL"],
  "agent_id": "agent_1234567890",
  "start_timestamp": {
    "gte": 1705320000,
    "lte": 1705406400
  }
}

​
Response Fields

​
data.calls
array
Array of call objects matching the filter criteria
​
data.pagination
object
Pagination metadataIncludes:
  • page: Current page number
  • limit: Results per page
  • total: Total number of calls matching filters
  • total_pages: Total number of pages
​
data.returned_count
integer
Number of calls returned in this response
​
data.applied_filters
object
The filter criteria that were applied to this query

​
Error Responses

​
error
string
Unauthorized - Missing or invalid API key/secret
​
error
string
Internal Server Error - Failed to retrieve calls

​
Notes

  • The organization ID is automatically extracted from your API key
  • All calls are automatically scoped to your organization
  • If no request body is provided, returns all calls with default pagination
  • Filtering is done at the database level for optimal performance
  • Date range filters use Unix timestamps (seconds)