# Request 1: Get all calls
curl -X GET "https://app.talkover.ai/api/v1/calls" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Request 1: Get all calls
const response = await fetch('https://app.talkover.ai/api/v1/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,
      "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
  }
}

GET

api

calls

# Request 1: Get all calls
curl -X GET "https://app.talkover.ai/api/v1/calls" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Request 1: Get all calls
const response = await fetch('https://app.talkover.ai/api/v1/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,
      "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
  }
}

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

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Query parameters

string

Filter by call status. Options: initiated, ringing, answered, completed, failed, busy, no-answer

string

Filter by call direction. Options: inbound, outbound

string

Filter by agent ID

string

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
curl -X GET "https://app.talkover.ai/api/v1/calls" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Request 1: Get all calls
const response = await fetch('https://app.talkover.ai/api/v1/calls', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here'
  }
});

const result = await response.json();
console.log(result);

# 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 2: Get completed calls from specific date
const response = await fetch('https://app.talkover.ai/api/v1/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: 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"

// Request 3: Search for specific phone number
const response = await fetch('https://app.talkover.ai/api/v1/calls?search=+1234567890&direction=outbound', {
  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,
      "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

boolean

required

Indicates if the operation was successful.

array

required

Array of call objects.

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

object

required

Agent information associated with the call.

Show Agent Object

string

required

Unique identifier for the agent.

string

required

Name of the agent.

string

required

Display label for the agent.

string

required

ISO 8601 timestamp when the call was created.

string

required

ISO 8601 timestamp when the call was last updated.

object

required

Pagination metadata.

Show Pagination Object

integer

required

Current page number.

integer

required

Last page number.

integer

required

Number of items per page.

integer

required

Total number of items.

integer

required

Starting item number for current page.

integer

required

Ending item number for current page.

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

Code	Description	HTTP Status
`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

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.

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

Get Started

Concepts

API Reference

Guides

List Calls

List Calls

Endpoint

Request headers

Query parameters

Example requests

Response

Success Response (200 OK)

Response fields

Error responses

401 Unauthorized

422 Validation Error

500 Server Error

Error codes

Important notes

​List Calls

​Endpoint

​Request headers

​Query parameters

​Example requests

​Response

​Success Response (200 OK)

​Response fields

​Error responses

​401 Unauthorized

​422 Validation Error

​500 Server Error

​Error codes

​Important notes

​Related endpoints

List Calls

Endpoint

Request headers

Query parameters

Example requests

Response

Success Response (200 OK)

Response fields

Error responses

401 Unauthorized

422 Validation Error

500 Server Error

Error codes

Important notes

Related endpoints