Calls

Read call records, transcripts, and audio URLs

Calls are read-only records created by the system when an agent handles a phone call. The API provides two levels of detail: a summary view (list) and a full detail view (individual call).

List vs detail view

Field	List	Detail
Basic info (name, phone, duration, status)	yes	yes
call_summary	yes	yes
transcript	—	yes
audio_file_url	—	yes
final_score	—	yes

Data model

Field	Type	Description
id	uuid	Call record identifier
call_id	string	LiveKit call identifier
customer_name	string	Caller’s name (if tracked)
customer_request	string	Subject of the call
phone_number	string	Caller’s phone number
duration	integer	Call duration in seconds
done	boolean	Whether the call has been processed
general_success	boolean	Whether the call was successful
disconnection_reason	string	user_hangup, call_transfer, agent_hangup
call_summary	string	AI-generated call summary
employee	string	Assigned employee name
note	string	Manual note added by staff
agent_id	uuid	Agent that handled the call
is_purged	boolean	Whether sensitive data has been purged
deleted_at	datetime	Soft-delete timestamp (null if not deleted)
created_at	datetime	Call start timestamp
updated_at	datetime	Last update timestamp

Detail-only fields:

Field	Type	Description
transcript	string	JSON string of conversation [{"role":"agent","text":"..."},...]
audio_file_url	string	Signed URL to call recording (expires after 1 hour)
final_score	integer	AI-generated quality score (1-10)

Endpoints

List calls

GET /v1/agents/{agentId}/calls

Permission: calls:read | Pagination: yes (ordered by created_at descending)

Soft-deleted calls are excluded by default.

Filters:

Parameter	Type	Description
done	boolean	Filter by completion status
from	datetime	Calls created after this date (ISO 8601)
to	datetime	Calls created before this date (ISO 8601)
phone_number	string	Exact match on caller phone number
search	string	Search in customer name, phone number, or summary
include_deleted	boolean	Include soft-deleted calls (default: false)

# Calls from the last 7 days that haven't been processed
curl -H "X-API-Key: $TP_KEY" \
  "$TP_BASE/agents/{agentId}/calls?from=2026-03-15T00:00:00Z&done=false"

Get call details

GET /v1/agents/{agentId}/calls/{callId}

Permission: calls:read

Returns full call details including transcript and audio URL.

Note: Purged calls (is_purged: true) will have transcript, audio_file_url, and phone_number set to null.

{
  "id": "call-uuid-1",
  "call_id": "lk_call_abc123",
  "customer_name": "Hans Meier",
  "customer_request": "Frage zu Rechnung #1234",
  "phone_number": "[phone]",
  "duration": 180,
  "done": true,
  "general_success": true,
  "final_score": 8,
  "disconnection_reason": "user_hangup",
  "call_summary": "Kunde fragte nach Rechnung #1234. Agent konnte Frage beantworten.",
  "transcript": "[{\"role\":\"agent\",\"text\":\"Guten Tag...\"},{\"role\":\"user\",\"text\":\"Hallo...\"}]",
  "audio_file_url": "https://storage.example.com/calls/abc123.wav",
  "employee": "Max Mustermann",
  "note": "Rueckruf vereinbart fuer Donnerstag",
  "is_purged": false,
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-03-19T10:30:00Z"
}

Transcript format

The transcript field is a JSON string containing an array of message objects:

[
  { "role": "agent", "text": "Guten Tag, wie kann ich Ihnen helfen?" },
  { "role": "user", "text": "Ich habe eine Frage zu meiner Rechnung." },
  { "role": "agent", "text": "Natuerlich, um welche Rechnung geht es?" }
]

Parse it in your application:

const messages = JSON.parse(call.transcript);
messages.forEach(m => console.log(`${m.role}: ${m.text}`));

Common patterns

Pull new calls since last sync

const lastSync = "2026-03-20T00:00:00Z";
const { data: newCalls } = await talkpilot(
  `/agents/${agentId}/calls?from=${lastSync}&limit=100`
);

Export all calls for a date range

const allCalls = [];
let page = 1, totalPages = 1;

while (page <= totalPages) {
  const res = await talkpilot(
    `/agents/${agentId}/calls?from=2026-03-01T00:00:00Z&to=2026-03-31T23:59:59Z&page=${page}&limit=100`
  );
  allCalls.push(...res.data);
  totalPages = res.pagination.pages;
  page++;
}

Related resources

• Agents — Parent resource
• Call Management — Dashboard UI guide