List Calls

Retrieve a paginated list of calls with optional filtering by status, direction, customer, and external reference IDs.

Request

curl -X GET "https://api.chanl.ai/api/v1/calls?status=ended&limit=20&page=1" \
  -H "Authorization: Bearer <access_token>"

curl -X GET "https://api.chanl.ai/api/v1/calls?externalRef.orderId=ORDER-12345" \
  -H "Authorization: Bearer <access_token>"

const params = new URLSearchParams({
  status: 'ended',
  limit: '20',
  page: '1'
});

const response = await fetch(`https://api.chanl.ai/api/v1/calls?${params}`, {
  headers: {
    'Authorization': 'Bearer ' + accessToken
  }
});

const { data } = await response.json();
console.log('Calls:', data.calls);
console.log('Total:', data.pagination.total);

import requests

response = requests.get(
    'https://api.chanl.ai/api/v1/calls',
    headers={'Authorization': f'Bearer {access_token}'},
    params={
        'status': 'ended',
        'limit': 20,
        'page': 1
    }
)

data = response.json()['data']
calls = data['calls']

Response

{
  "success": true,
  "data": {
    "calls": [
      {
        "id": "695d6957e21c0ceb325c394d",
        "workspaceId": "ws_123",
        "status": "ended",
        "direction": "inbound",
        "customerName": "John Smith",
        "agentName": "Agent One",
        "duration": 180,
        "score": 85,
        "externalReferenceIds": {
          "orderId": "ORDER-12345",
          "customerId": "cust_abc123"
        },
        "createdAt": "2026-01-06T10:00:00Z",
        "updatedAt": "2026-01-06T10:03:00Z"
      }
    ],
    "pagination": {
      "total": 150,
      "page": 1,
      "limit": 20,
      "totalPages": 8
    }
  }
}

Query Parameters

Standard Filters

statusstring

Filter by call status: queued, ringing, in_progress, ended, failed

directionstring

Filter by call direction: inbound, outbound

customerNamestring

Filter by customer name (partial match).

agentIdstring

Filter by agent ID.

scenarioIdstring

Filter by scenario ID.

startDatestring

Filter calls on or after this date (ISO 8601).

endDatestring

Filter calls on or before this date (ISO 8601).

External Reference Filters

Filter calls by any external reference ID stored during import. The query parameter format is externalRef.{key}={value}.

externalRef.{key}string

Filter by external reference. Replace {key} with your custom key.

Examples:

externalRef.orderId=ORDER-12345
externalRef.customerId=cust_abc123
externalRef.ticketId=TICKET-789

Pagination

pageintegerdefault: 1

Page number (1-indexed).

limitintegerdefault: 20

Items per page (max 100).

sortBystringdefault: createdAt

Sort field: createdAt, duration, score

sortOrderstringdefault: desc

Sort order: asc, desc

External Reference Filtering Examples

curl -X GET "https://api.chanl.ai/api/v1/calls?externalRef.orderId=ORDER-12345" \
  -H "Authorization: Bearer <access_token>"

curl -X GET "https://api.chanl.ai/api/v1/calls?externalRef.customerId=cust_abc123" \
  -H "Authorization: Bearer <access_token>"

curl -X GET "https://api.chanl.ai/api/v1/calls?externalRef.customerId=cust_789&externalRef.orderId=ORDER-123&status=ended" \
  -H "Authorization: Bearer <access_token>"

Response Fields

Field	Type	Description
`id`	string	Unique call identifier
`workspaceId`	string	Workspace the call belongs to
`status`	string	Call status
`direction`	string	Call direction (inbound/outbound)
`customerName`	string	Customer name
`agentName`	string	Agent name
`duration`	number	Call duration in seconds
`score`	number	Overall scorecard score (if evaluated)
`externalReferenceIds`	object	Your external system IDs
`createdAt`	string	When the call was created
`updatedAt`	string	When the call was last updated