Skip to main content
GET
/
api
/
v1
/
calls
# Request 1: Get all calls
curl -X GET "https://app.talkover.ai/api/v1/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,
      "agent": {
        "id": "agent-uuid-1",
        "name": "Sales Agent",
        "label": "Sales Agent Label"
      },
      "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,
      "agent": {
        "id": "agent-uuid-2",
        "name": "Support Agent",
        "label": "Support Agent Label"
      },
      "created_at": "2024-01-01T01:00:00Z",
      "updated_at": "2024-01-01T01:03:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100,
    "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.

​
List Calls

Retrieve a list of all calls for the authenticated environment with various filtering options and pagination support.

​
Endpoint

GET /api/v1/calls

​
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
​
agent_id
string
Filter by agent ID
​
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
curl -X GET "https://app.talkover.ai/api/v1/calls" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 2: Get completed calls from specific date
curl -X GET "https://app.talkover.ai/api/v1/calls?status=completed&date_from=2024-01-01&per_page=50" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 3: Search for specific phone number
curl -X GET "https://app.talkover.ai/api/v1/calls?search=+1234567890&direction=outbound" \
  -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,
      "agent": {
        "id": "agent-uuid-1",
        "name": "Sales Agent",
        "label": "Sales Agent Label"
      },
      "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,
      "agent": {
        "id": "agent-uuid-2",
        "name": "Support Agent",
        "label": "Support Agent Label"
      },
      "created_at": "2024-01-01T01:00:00Z",
      "updated_at": "2024-01-01T01:03:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100,
    "from": 1,
    "to": 20
  }
}

​
Response Fields

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

​
Error Responses

​
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
INVALID_TOKENAuthentication token is invalid or missing401
VALIDATION_ERRORQuery parameter validation failed422
SERVER_ERRORInternal server error occurred500

​
Important Notes

Pagination support. All list endpoints support pagination with page and per_page parameters.
Date filtering. Use date_from and date_to to filter calls by date range.
Search functionality. The search parameter searches in phone numbers and call SIDs.

​
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. Search efficiently - Use the search parameter to find specific calls quickly
  4. Monitor status - Filter by status to track call progress
  5. Handle errors - Implement proper error handling for authentication and validation failures
  • Get Agent Calls: GET /api/v1/agents/{agent_id}/calls
  • List Campaigns: GET /api/v1/campaigns
  • Make a Call: POST /api/v1/calls