Returns a paginated list of calls for your organization. By default, chat_history (transcript) is not included — pass include_transcript=true to include it. Supports filtering by date range, status, result, agent, and campaign.
Your API key for authentication. Found in your dashboard under API settings.
Query Parameters limit
number
predeterminado: "20"
Maximum number of calls to return. Must be ≥ 0.
Number of records to skip for pagination. Must be ≥ 0.
order
string
predeterminado: "desc"
Sort direction by creation date. Possible values: asc, desc.
Filter calls created on or after this date (ISO 8601, e.g. 2026-01-01).
Filter calls created on or before this date (ISO 8601, e.g. 2026-04-01).
Filter by call status. Possible values: in-progress, completed, no-answer, failed, in-queue, incomplete, busy, answering-machine, scheduled, voice_mail.
Filter by call result. Possible values: answered, voicemail, no_answer, busy, failed.
Filter by phone number in E.164 format (e.g. +12124567890).
include_transcript
boolean
predeterminado: "false"
Include chat_history (transcript) in each call record. Defaults to false.
include_words
boolean
predeterminado: "false"
Include per-word timing data in transcript entries. Only applies when include_transcript=true.
include_tools
boolean
predeterminado: "false"
Include chat_history_with_tools in each call record.
transcript_format
string
predeterminado: "json"
Format for transcript output. Possible values: json (raw array), toon (token-efficient TOON encoding). Only applies when include_transcript=true or include_tools=true.
Response Array of call objects. Unique identifier of the call (UUID).
Call direction: inbound or outbound.
The phone number that initiated the call (E.164 format).
URL to the call recording, if available.
Current status of the call (e.g. completed, no-answer, failed).
Outcome of the call (e.g. answered, voicemail, no_answer).
Reason the call was disconnected, if applicable.
Timestamp when the call ended (ISO 8601).
Timestamp when the call started (ISO 8601).
Call duration in seconds.
AI-generated analysis of the call (summary, sentiment, etc.).
Timestamp when the call record was created (ISO 8601).
UUID of the AI agent that handled the call.
UUID of the campaign this call belongs to, if any.
Contact associated with the call. Transcript of the call. Present only when include_transcript=true. Returns an array of transcript entries (JSON format) or a TOON-encoded string when transcript_format=toon.
Transcript including tool calls. Present only when include_tools=true.
Format used for transcript fields. Present when transcript is included.
Total number of calls matching the query (before pagination).
Error Codes
400 Bad Request — Invalid query parameters401 Unauthorized — Invalid or missing API key500 Internal Server Error — Server-side error
Code Examples cURL — Basic list
cURL — Filtered with transcript
JavaScript
Python
curl -X GET "https://api.contactship.ai/v1/calls?limit=20&offset=0" \ -H "x-api-key: your-api-key"
{ "data" : [ { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "direction" : "outbound" , "from" : "+12025551234" , "call_record" : "https://api.contactship.ai/recordings/a1b2c3d4.mp3" , "call_status" : "completed" , "call_result" : "answered" , "disconnection_reason" : "agent_hangup" , "finished_at" : "2026-03-15T14:35:22Z" , "start_at" : "2026-03-15T14:30:05Z" , "duration" : 317 , "call_analysis" : { "summary" : "Customer expressed interest in the premium plan and requested a demo." , "sentiment" : "positive" }, "type" : "ai_call" , "created_at" : "2026-03-15T14:30:00Z" , "agent_id" : "f1e2d3c4-b5a6-7890-1234-567890abcdef" , "campaign_id" : null , "contact" : { "id" : "c1d2e3f4-a5b6-7890-cdef-123456789012" , "full_name" : "Jane Smith" , "phone_number" : "+14155552678" , "email" : "jane.smith@example.com" , "country" : "US" } } ], "count" : 142 }
