> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Call

> Retrieve full details of a single call by its ID

Returns the full details of a single call. The transcript (`chat_history`) is **included by default** — pass `include_transcript=false` to omit it. Use `include_words=true` for per-word timing data, or `transcript_format=toon` for a token-efficient encoding.

## Path Parameters

<ParamField path="callId" type="string" required>
  The UUID of the call to retrieve.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication. Found in your dashboard under API settings.
</ParamField>

## Query Parameters

<ParamField query="include_transcript" type="boolean" default="true">
  Include `chat_history` (transcript) in the response. Defaults to `true`.
</ParamField>

<ParamField query="include_words" type="boolean" default="false">
  Include per-word timing data in transcript entries. Only applies when `include_transcript=true`.
</ParamField>

<ParamField query="include_tools" type="boolean" default="false">
  Include `chat_history_with_tools` in the response.
</ParamField>

<ParamField query="transcript_format" type="string" default="json">
  Format for transcript output. Possible values: `json` (raw array), `toon` (token-efficient TOON encoding).
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the call (UUID).
</ResponseField>

<ResponseField name="direction" type="string">
  Call direction: `inbound` or `outbound`.
</ResponseField>

<ResponseField name="from" type="string">
  The phone number that initiated the call (E.164 format).
</ResponseField>

<ResponseField name="call_record" type="string">
  URL to the call recording, if available.
</ResponseField>

<ResponseField name="call_status" type="string">
  Status of the call. Possible values: `in-progress`, `completed`, `no-answer`, `failed`, `in-queue`, `incomplete`, `busy`, `answering-machine`, `scheduled`, `voice_mail`.
</ResponseField>

<ResponseField name="call_result" type="string">
  Outcome of the call. Possible values: `answered`, `voicemail`, `no_answer`, `busy`, `failed`.
</ResponseField>

<ResponseField name="disconnection_reason" type="string">
  Reason the call was disconnected, if applicable.
</ResponseField>

<ResponseField name="finished_at" type="string">
  Timestamp when the call ended (ISO 8601).
</ResponseField>

<ResponseField name="start_at" type="string">
  Timestamp when the call started (ISO 8601).
</ResponseField>

<ResponseField name="duration" type="number">
  Call duration in seconds.
</ResponseField>

<ResponseField name="call_analysis" type="object">
  AI-generated analysis of the call (summary, sentiment, etc.).
</ResponseField>

<ResponseField name="type" type="string">
  Call type identifier.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the call record was created (ISO 8601).
</ResponseField>

<ResponseField name="agent_id" type="string">
  UUID of the AI agent that handled the call.
</ResponseField>

<ResponseField name="contact" type="object">
  Contact associated with the call.

  <Expandable title="Contact object">
    <ResponseField name="id" type="string">Contact UUID.</ResponseField>
    <ResponseField name="full_name" type="string">Contact full name.</ResponseField>
    <ResponseField name="phone_number" type="string">Contact phone number.</ResponseField>
    <ResponseField name="email" type="string">Contact email address.</ResponseField>
    <ResponseField name="country" type="string">Contact country code.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chat_history" type="array or string">
  Transcript of the call. Present when `include_transcript=true` (default). Returns an array of transcript entries (JSON format) or a TOON-encoded string when `transcript_format=toon`.

  <Expandable title="Transcript entry (JSON format)">
    <ResponseField name="role" type="string">Speaker role: `agent` or `user`.</ResponseField>
    <ResponseField name="content" type="string">Spoken content.</ResponseField>
    <ResponseField name="words" type="array">Per-word timing data. Present only when `include_words=true`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chat_history_with_tools" type="array or string">
  Full transcript including tool/function calls. Present when `include_tools=true`.
</ResponseField>

<ResponseField name="transcript_format" type="string">
  Format used for transcript fields. Present when transcript is included.
</ResponseField>

## Error Codes

* `401 Unauthorized` — Invalid or missing API key
* `404 Not Found` — Call not found or does not belong to your organization
* `500 Internal Server Error` — Server-side error

## Code Examples

<RequestExample>
  ```bash cURL — With transcript (default) theme={null}
  curl -X GET "https://api.contactship.ai/v1/calls/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
    -H "x-api-key: your-api-key"
  ```

  ```bash cURL — TOON transcript format theme={null}
  curl -X GET "https://api.contactship.ai/v1/calls/a1b2c3d4-e5f6-7890-abcd-ef1234567890?transcript_format=toon" \
    -H "x-api-key: your-api-key"
  ```

  ```bash cURL — No transcript theme={null}
  curl -X GET "https://api.contactship.ai/v1/calls/a1b2c3d4-e5f6-7890-abcd-ef1234567890?include_transcript=false" \
    -H "x-api-key: your-api-key"
  ```

  ```javascript JavaScript theme={null}
  const getCall = async (callId, params = {}) => {
    const query = new URLSearchParams(params).toString();
    const response = await fetch(
      `https://api.contactship.ai/v1/calls/${callId}${query ? `?${query}` : ''}`,
      { headers: { 'x-api-key': 'your-api-key' } }
    );
    if (response.status === 404) throw new Error('Call not found');
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  };

  // Example: get call with word-level timing data
  const call = await getCall('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
    include_words: true,
  });
  console.log(`Call duration: ${call.duration}s, result: ${call.call_result}`);
  ```

  ```python Python theme={null}
  import requests

  api_key = "your-api-key"
  call_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  response = requests.get(
      f"https://api.contactship.ai/v1/calls/{call_id}",
      headers={"x-api-key": api_key},
      params={"include_words": True},
  )

  if response.status_code == 200:
      call = response.json()
      print(f"Duration: {call['duration']}s, Result: {call['call_result']}")
      if call.get("chat_history"):
          print(f"Transcript entries: {len(call['chat_history'])}")
  elif response.status_code == 404:
      print("Call not found")
  else:
      print(f"Error {response.status_code}: {response.text}")
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "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",
    "contact": {
      "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "full_name": "Jane Smith",
      "phone_number": "+14155552678",
      "email": "jane.smith@example.com",
      "country": "US"
    },
    "chat_history": [
      {
        "role": "agent",
        "content": "Hello, this is an AI assistant calling from ContactShip. Am I speaking with Jane?"
      },
      {
        "role": "user",
        "content": "Yes, this is Jane."
      },
      {
        "role": "agent",
        "content": "Great! I'm reaching out about our premium plan. Do you have a moment to chat?"
      }
    ],
    "transcript_format": "json"
  }
  ```
</ResponseExample>