# Request 1: Get all calls for a specific agent
curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all calls for a specific agent
const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"success": true,
"data": [
{
"id": "call-uuid-1",
"sid": "call_sid_123",
"to": "+1234567890",
"to_formatted": "(123) 456-7890",
"from": "+0987654321",
"from_formatted": "(098) 765-4321",
"is_testing": false,
"direction": "outbound",
"status": "completed",
"duration": 120,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
{
"id": "call-uuid-2",
"sid": "call_sid_456",
"to": "+1987654321",
"to_formatted": "(987) 654-3210",
"from": "+0987654321",
"from_formatted": "(098) 765-4321",
"is_testing": false,
"direction": "inbound",
"status": "answered",
"duration": 180,
"created_at": "2024-01-01T01:00:00Z",
"updated_at": "2024-01-01T01:03:00Z"
}
],
"pagination": {
"current_page": 1,
"last_page": 3,
"per_page": 20,
"total": 50,
"from": 1,
"to": 20
}
}
Calls & Campaigns
Get Agent Calls
Retrieve all calls for a specific agent with filtering and pagination
GET
/
api
/
v1
/
agents
/
{agent_id}
/
calls
# Request 1: Get all calls for a specific agent
curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all calls for a specific agent
const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"success": true,
"data": [
{
"id": "call-uuid-1",
"sid": "call_sid_123",
"to": "+1234567890",
"to_formatted": "(123) 456-7890",
"from": "+0987654321",
"from_formatted": "(098) 765-4321",
"is_testing": false,
"direction": "outbound",
"status": "completed",
"duration": 120,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
{
"id": "call-uuid-2",
"sid": "call_sid_456",
"to": "+1987654321",
"to_formatted": "(987) 654-3210",
"from": "+0987654321",
"from_formatted": "(098) 765-4321",
"is_testing": false,
"direction": "inbound",
"status": "answered",
"duration": 180,
"created_at": "2024-01-01T01:00:00Z",
"updated_at": "2024-01-01T01:03:00Z"
}
],
"pagination": {
"current_page": 1,
"last_page": 3,
"per_page": 20,
"total": 50,
"from": 1,
"to": 20
}
}
Get Agent Calls
Retrieve all calls for a specific agent with various filtering options and pagination support.Endpoint
GET /api/v1/agents/{agent_id}/calls
Path parameters
string
required
The unique identifier of the agent.
Request headers
string
required
Bearer token for authentication. Format:
Bearer talq_your_environment_token_hereQuery parameters
string
Adds the conversation result to each call. Only accepted value:
insight. Any other value returns 422. See List calls for the fields.string
Filter by call status. Options:
initiated, ringing, answered, completed, failed, busy, no-answerstring
Filter by call direction. Options:
inbound, outboundstring
Filter calls from date (YYYY-MM-DD)
string
Filter calls to date (YYYY-MM-DD)
string
Search in phone numbers or call SID
integer
Number of items per page (default: 20, max: 100)
integer
Page number (default: 1)
Example requests
# Request 1: Get all calls for a specific agent
curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all calls for a specific agent
const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
# Request 2: Get completed calls for agent from specific date
curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?status=completed&date_from=2024-01-01&per_page=50" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 2: Get completed calls for agent from specific date
const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?status=completed&date_from=2024-01-01&per_page=50', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
# Request 3: Get outbound calls for agent with search
curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?direction=outbound&search=+1234567890" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 3: Get outbound calls for agent with search
const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?direction=outbound&search=+1234567890', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
Response
Success Response (200 OK)
{
"success": true,
"data": [
{
"id": "call-uuid-1",
"sid": "call_sid_123",
"to": "+1234567890",
"to_formatted": "(123) 456-7890",
"from": "+0987654321",
"from_formatted": "(098) 765-4321",
"is_testing": false,
"direction": "outbound",
"status": "completed",
"duration": 120,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
},
{
"id": "call-uuid-2",
"sid": "call_sid_456",
"to": "+1987654321",
"to_formatted": "(987) 654-3210",
"from": "+0987654321",
"from_formatted": "(098) 765-4321",
"is_testing": false,
"direction": "inbound",
"status": "answered",
"duration": 180,
"created_at": "2024-01-01T01:00:00Z",
"updated_at": "2024-01-01T01:03:00Z"
}
],
"pagination": {
"current_page": 1,
"last_page": 3,
"per_page": 20,
"total": 50,
"from": 1,
"to": 20
}
}
Response fields
boolean
required
Indicates if the operation was successful.
array
required
Array of call objects for the specific agent.
Show Call Object
Show Call Object
string
required
Unique identifier for the call.
string
required
Call SID from the telephony provider.
string
required
Destination phone number in E.164 format.
string
required
Formatted destination phone number for display.
string
required
Source phone number in E.164 format.
string
required
Formatted source phone number for display.
boolean
required
Whether this is a test call.
string
required
Direction of the call. Options:
inbound, outbound.string
required
Current status of the call. Options:
initiated, ringing, answered, completed, failed, busy, no-answer.integer
required
Call duration in seconds (0 if not completed).
string
required
ISO 8601 timestamp when the call was created.
string
required
ISO 8601 timestamp when the call was last updated.
object
required
Error responses
404 Not Found
{
"success": false,
"message": "Agent not found"
}
401 Unauthorized
{
"success": false,
"message": "Unauthorized"
}
422 Validation Error
{
"success": false,
"message": "The given data was invalid.",
"errors": {
"status": [
"The selected status is invalid."
],
"direction": [
"The selected direction is invalid."
],
"date_from": [
"The date from must be a valid date."
]
}
}
500 Server Error
{
"success": false,
"message": "Internal server error."
}
Error codes
| Code | Description | HTTP Status |
|---|---|---|
AGENT_NOT_FOUND | Specified agent does not exist | 404 |
INVALID_TOKEN | Authentication token is invalid or missing | 401 |
VALIDATION_ERROR | Query parameter validation failed | 422 |
SERVER_ERROR | Internal server error occurred | 500 |
Important notes
Agent-specific filtering. This endpoint returns only calls associated with the specified agent.
Same filtering options. All filtering options from the main calls endpoint are available.
No agent object. The response doesn’t include the agent object since it’s already specified in the URL.
Conversation result. Pass
include=insight to get analysis_status, human_detected, call_result, collected_data and campaign_id on each call. Without it the response is unchanged.Related endpoints
- List Calls:
GET /api/v1/calls - Get Agent:
GET /api/v1/agents/{agent_id} - List Campaigns:
GET /api/v1/campaigns - Get call insight:
GET /api/v1/calls/{call_id}/insight
Was this page helpful?