# 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
  }
}

GET

api

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

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.

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)

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.

Show Call Object

string

required

Unique identifier for the call.

sid

string

required

Call SID from the telephony provider.

string

required

Destination phone number in E.164 format.

to_formatted

string

required

Formatted destination phone number for display.

from

string

required

Source phone number in E.164 format.

from_formatted

string

required

Formatted source phone number for display.

is_testing

boolean

required

Whether this is a test call.

direction

string

required

Direction of the call. Options: inbound, outbound.

status

string

required

Current status of the call. Options: initiated, ringing, answered, completed, failed, busy, no-answer.

duration

integer

required

Call duration in seconds (0 if not completed).

created_at

string

required

ISO 8601 timestamp when the call was created.

updated_at

string

required

ISO 8601 timestamp when the call was last updated.

pagination

object

required

Pagination metadata.

Show Pagination Object

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.

List Calls: GET /api/v1/calls
Get Agent: GET /api/v1/agents/{agent_id}
List Campaigns: GET /api/v1/campaigns

List Calls List Campaigns

​Get Agent Calls

​Endpoint

​Path parameters

​Request headers

​Query parameters

​Example requests

​Response

​Success Response (200 OK)

​Response fields

​Error responses

​404 Not Found

​401 Unauthorized

​422 Validation Error

​500 Server Error

​Error codes

​Important notes

​Related endpoints

Get Agent Calls

Endpoint

Path parameters

Request headers

Query parameters

Example requests

Response

Success Response (200 OK)

Response fields

Error responses

404 Not Found

401 Unauthorized

422 Validation Error

500 Server Error

Error codes

Important notes

Related endpoints