> ## 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 Status

> Where a call is right now: ringing, in progress or finished

A light read meant for polling while a call runs, for example to show a live call in your own interface. It answers in a few fields and never carries the transcript.

`finished` turns `true` seconds after the hang-up. The analysis, the recording and the transcript arrive later: read them with [Get Call](/api-reference/endpoint/get-call) once the call is finished. To hang up from your interface, use [Stop Call](/api-reference/endpoint/stop-call).

## Path Parameters

<ParamField path="callId" type="string" required>
  The UUID of the call, as returned by [Make AI Phone Call](/api-reference/endpoint/make-ai-phone-call).
</ParamField>

## Headers

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

## Response

The response is `{ "statusCode": number, "data": object }`. The fields below describe `data`.

<ResponseField name="call_id" type="string">
  The UUID of the call.
</ResponseField>

<ResponseField name="agent_id" type="string">
  The agent placing the call.
</ResponseField>

<ResponseField name="call_status" type="string">
  Where the call is: `in_queue` or `scheduled` before it is placed, `pending` while it rings, `in_progress` once answered, and `ended`, `voicemail`, `no_answer`, `failed` or `canceled` when it is over.
</ResponseField>

<ResponseField name="finished" type="boolean">
  Whether the call is over.
</ResponseField>

<ResponseField name="disconnection_reason" type="string">
  Why the call ended, e.g. `user_hangup` or `agent_hangup`. It can stay `null` for a few seconds after `finished` turns `true`.
</ResponseField>

<ResponseField name="started_at" type="string">
  When the call was answered (ISO 8601), or `null`.
</ResponseField>

<ResponseField name="ended_at" type="string">
  When the call ended (ISO 8601), or `null`.
</ResponseField>

## Error Codes

* `400 Bad Request` — `callId` is not a valid UUID
* `401 Unauthorized` — Invalid or missing API key
* `404 Not Found` — Call not found or does not belong to your organization
* `429 Too Many Requests` — Poll every few seconds, not in a tight loop. See [Rate limits](/api-reference/rate-limits)

## Code Examples

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

  ```javascript JavaScript theme={null}
  const waitUntilFinished = async (callId) => {
    while (true) {
      const response = await fetch(
        `https://api.contactship.ai/v1/calls/${callId}/status`,
        { headers: { 'x-api-key': 'your-api-key' } }
      );
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      const { data } = await response.json();
      if (data.finished) return data;
      await new Promise((resolve) => setTimeout(resolve, 4000));
    }
  };
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "statusCode": 200,
    "data": {
      "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "call_status": "in_progress",
      "finished": false,
      "disconnection_reason": null,
      "started_at": "2026-10-07T18:00:05.000Z",
      "ended_at": null
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.