Skip to main content
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"

{
  "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
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
agent
string
required
The unique identifier of the agent. You can find this in your dashboard under Voice Agents.

​
Request Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here

​
Query Parameters

​
status
string
Filter by call status. Options: initiated, ringing, answered, completed, failed, busy, no-answer
​
direction
string
Filter by call direction. Options: inbound, outbound
​
date_from
string
Filter calls from date (YYYY-MM-DD)
​
date_to
string
Filter calls to date (YYYY-MM-DD)
​
search
string
Search in phone numbers or call SID
​
per_page
integer
Number of items per page (default: 20, max: 100)
​
page
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 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 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"

​
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

​
success
boolean
required
Indicates if the operation was successful.
​
data
array
required
Array of call objects for the specific agent.
​
pagination
object
required
Pagination metadata.

​
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

CodeDescriptionHTTP Status
AGENT_NOT_FOUNDSpecified agent does not exist404
INVALID_TOKENAuthentication token is invalid or missing401
VALIDATION_ERRORQuery parameter validation failed422
SERVER_ERRORInternal server error occurred500

​
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.

​
Best Practices

  1. Use pagination - Always use pagination for large datasets
  2. Filter by date - Use date filters to limit results to relevant time periods
  3. Monitor performance - Track call status and duration for agent performance analysis
  4. Search efficiently - Use the search parameter to find specific calls quickly
  5. Handle errors - Implement proper error handling for authentication and validation failures
  • List Calls: GET /api/v1/calls
  • Get Agent: GET /api/v1/agents/{agent_id}
  • List Campaigns: GET /api/v1/campaigns