Call logs

The Calls API provides access to call history, recordings, transcripts, and real-time call events.

Base URL: https://api.krosai.com/v1/calls

List Calls

Retrieve call history with filtering and pagination.

GET /calls

Query Parameters

Parameter	Type	Description
status	string	Filter by status: completed, failed, in_progress
direction	string	Filter by direction: inbound, outbound
phone_number_id	string	Filter by phone number
endpoint_id	string	Filter by endpoint
from_date	string	Start date (ISO 8601)
to_date	string	End date (ISO 8601)
limit	integer	Results per page (default: 50, max: 100)
offset	integer	Pagination offset

Request

curl

curl -X GET "https://api.krosai.com/v1/calls?limit=10&status=completed" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "calls": [
    {
      "id": "call_abc123",
      "from_number": "[phone]",
      "to_number": "[phone]",
      "direction": "inbound",
      "status": "completed",
      "duration": 180,
      "cost_cents": 12,
      "endpoint_id": "ep_xyz789",
      "phone_number_id": "pn_123",
      "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3",
      "transcript": "Hello, how can I help you today?...",
      "created_at": "2025-01-10T10:00:00Z",
      "answered_at": "2025-01-10T10:00:05Z",
      "completed_at": "2025-01-10T10:03:05Z"
    }
  ],
  "total": 156,
  "limit": 10,
  "offset": 0
}

Get Call

Retrieve detailed information about a specific call.

GET /calls/{id}

Request

curl

curl -X GET "https://api.krosai.com/v1/calls/call_abc123" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "id": "call_abc123",
  "from_number": "[phone]",
  "to_number": "[phone]",
  "direction": "inbound",
  "status": "completed",
  "duration": 180,
  "cost_cents": 12,
  "endpoint": {
    "id": "ep_xyz789",
    "name": "Support Agent",
    "provider": "elevenlabs"
  },
  "phone_number": {
    "id": "pn_123",
    "number": "[phone]"
  },
  "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3",
  "transcript": "Hello, how can I help you today? I'm looking for information about...",
  "quality_metrics": {
    "latency_ms": 120,
    "audio_codec": "opus",
    "packet_loss": 0.01
  },
  "hangup_cause": "normal_clearing",
  "created_at": "2025-01-10T10:00:00Z",
  "answered_at": "2025-01-10T10:00:05Z",
  "completed_at": "2025-01-10T10:03:05Z"
}

Get Call Statistics

Get aggregated statistics for calls.

GET /calls/stats

Query Parameters

Parameter	Type	Description
phone_number_id	string	Filter by phone number
endpoint_id	string	Filter by endpoint
from_date	string	Start date (ISO 8601)
to_date	string	End date (ISO 8601)

Request

curl

curl -X GET "https://api.krosai.com/v1/calls/stats?from_date=2025-01-01" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "total_calls": 1250,
  "completed_calls": 1180,
  "failed_calls": 70,
  "total_duration_seconds": 45000,
  "average_duration_seconds": 38,
  "total_cost_cents": 3600,
  "inbound_calls": 800,
  "outbound_calls": 450,
  "success_rate": 0.944
}

Get Call Events

Retrieve the event timeline for a specific call.

GET /calls/{id}/events

Request

curl

curl -X GET "https://api.krosai.com/v1/calls/call_abc123/events" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "events": [
    {
      "id": "evt_001",
      "event_type": "call_initiated",
      "created_at": "2025-01-10T10:00:00Z",
      "event_data": {}
    },
    {
      "id": "evt_002",
      "event_type": "sip_invite_sent",
      "created_at": "2025-01-10T10:00:01Z",
      "event_data": {
        "sip_uri": "sip:[email protected]"
      }
    },
    {
      "id": "evt_003",
      "event_type": "call_answered",
      "created_at": "2025-01-10T10:00:05Z",
      "event_data": {}
    },
    {
      "id": "evt_004",
      "event_type": "sip_media_established",
      "created_at": "2025-01-10T10:00:06Z",
      "event_data": {
        "codec": "opus",
        "latency_ms": 120
      }
    },
    {
      "id": "evt_005",
      "event_type": "call_completed",
      "created_at": "2025-01-10T10:03:05Z",
      "event_data": {
        "duration": 180,
        "hangup_cause": "normal_clearing"
      }
    }
  ]
}

Hangup Call

Terminate an active call.

POST /calls/{id}/hangup

Request

curl

curl -X POST "https://api.krosai.com/v1/calls/call_abc123/hangup" \
  -H "x-api-key: kros_live_your_key"

Response

{
  "success": true,
  "message": "Call hangup initiated"
}

Call Status Values

Status	Description
initiated	Call is being set up
ringing	Destination is ringing
in_progress	Call is active
completed	Call ended normally
failed	Call failed to connect
busy	Destination was busy
no_answer	No answer at destination

Hangup Causes

Cause	Description
normal_clearing	Normal call termination
user_hangup	Caller hung up
agent_hangup	Agent/endpoint hung up
no_answer	Destination didn't answer
busy	Destination busy
rejected	Call rejected
network_error	Network failure
timeout	Call timed out

Recordings

Call recordings are automatically generated for completed calls and stored securely.

Recording URL

Recordings are available via the recording_url field:

https://storage.krosai.com/recordings/call_abc123.mp3

Recording Formats

• Format: MP3

• Sample Rate: 48kHz

• Channels: Mono (mixed)

• Retention: 90 days (configurable)

Transcripts

Full transcripts are generated using speech-to-text and available in the transcript field.

Transcript Format

Plain text with speaker labels (when available):

[Agent]: Hello, how can I help you today?
[Caller]: Hi, I'm calling about my order status.
[Agent]: I'd be happy to help. Can you provide your order number?
...

Code Examples

TypeScript

examples/calls.ts

// List recent call
async function listCalls(options?: {
  status?: string;
  direction?: string;
  limit?: number;
}) {
  const params = new URLSearchParams();
  if (options?.status) params.set('status', options.status);
  if (options?.direction) params.set('direction', options.direction);
  if (options?.limit) params.set('limit', options.limit.toString());
  
  const response = await fetch(
    `https://api.krosai.com/v1/calls?${params}`,
    {
      headers: { 'x-api-key': process.env.KROSAI_API_KEY! },
    }
  );
  
  return response.json();
}

// Get call details with recording
async function getCallWithRecording(callId: string) {
  const response = await fetch(
    `https://api.krosai.com/v1/calls/${callId}`,
    {
      headers: { 'x-api-key': process.env.KROSAI_API_KEY! },
    }
  );
  
  const call = await response.json();
  
  if (call.recording_url) {
    console.log(`Recording available: ${call.recording_url}`);
  }
  
  return call;
}

// Hangup an active call
async function hangupCall(callId: string) {
  const response = await fetch(
    `https://api.krosai.com/v1/calls/${callId}/hangup`,
    {
      method: 'POST',
      headers: { 'x-api-key': process.env.KROSAI_API_KEY! },
    }
  );
  
  return response.json();
}

Python