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

# Get a Call Recording — Shilo API GET /api/v1/calls

> Retrieve a single non-roleplay call by Shilo UUID, call event ID, or your external recording ID. Returns the complete Call object with all fields.

This endpoint retrieves a single call recording by one of three supported identifier formats. You can look up a call using Shilo's own UUID, the `call_event_id` returned when you submitted the call for processing, or your own external recording identifier. This flexibility means you can integrate Shilo lookups without needing to store Shilo-internal IDs in your own systems.

## Endpoint

```text theme={null}
GET https://api.shilo.ai/api/v1/calls/{identifier}
```

## Path Parameter

<ParamField path="identifier" type="string" required>
  Identifies the call to retrieve. Three formats are accepted:

  | Format                           | Example                                              | When to use                                                                                                                 |
  | -------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
  | `{uuid}`                         | `ee6f2136-b94a-4438-9335-3acf5b2a0d31`               | You already have the Shilo Call UUID (e.g. from `GET /calls`).                                                              |
  | `call_event_id:{uuid}`           | `call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31` | You just submitted a call via `POST /calls` and want to check its status. Use the `call_event_id` value from that response. |
  | `external_recording_id:{string}` | `external_recording_id:rec-20300924-001`             | You want to look up a call using the `recording_id` your system provided at submission time.                                |
</ParamField>

## Response

A successful request returns HTTP `200` with the full Call object.

<ResponseField name="id" type="string">
  Shilo's unique UUID for this call recording.
</ResponseField>

<ResponseField name="type" type="string">
  Resource type identifier. Always `"call"` for this endpoint.
</ResponseField>

<ResponseField name="created_date" type="string">
  ISO-8601 timestamp of when the call was ingested by Shilo.
</ResponseField>

<ResponseField name="duration" type="number">
  Length of the call in seconds.
</ResponseField>

<ResponseField name="external_user_id" type="string">
  Your system's identifier for the agent on this call.
</ResponseField>

<ResponseField name="user_id" type="string">
  Shilo's UUID for the agent on this call.
</ResponseField>

<ResponseField name="external_contact_id" type="string">
  Your system's identifier for the contact on this call.
</ResponseField>

<ResponseField name="contact_id" type="string">
  Shilo's UUID for the contact on this call.
</ResponseField>

<ResponseField name="from_number" type="string">
  The phone number the call originated from, in display format.
</ResponseField>

<ResponseField name="to_number" type="string">
  The phone number the call was placed to, in display format.
</ResponseField>

<ResponseField name="incoming" type="boolean">
  `true` if the call was inbound (received by the agent); `false` if outbound.
</ResponseField>

<ResponseField name="source" type="string">
  Human-readable name of the recording source (e.g. `"Broker"`).
</ResponseField>

<ResponseField name="source_id" type="string">
  Identifier of the recording source.
</ResponseField>

<ResponseField name="stage" type="string">
  Human-readable sales stage associated with the contact at call time.
</ResponseField>

<ResponseField name="stage_id" type="string">
  Identifier of the associated sales stage.
</ResponseField>

<ResponseField name="external_recording_id" type="string">
  The `recording_id` your system supplied when this call was submitted via `POST /calls`.
</ResponseField>

## Example Requests

**Look up by Shilo Call UUID:**

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/calls/ee6f2136-b94a-4438-9335-3acf5b2a0d31" \
  --header "x-api-key: YOUR_API_KEY"
```

**Look up immediately after submission using `call_event_id`:**

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/calls/call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31" \
  --header "x-api-key: YOUR_API_KEY"
```

**Look up using your own external recording ID:**

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/calls/external_recording_id:rec-20300924-001" \
  --header "x-api-key: YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "type": "call",
  "created_date": "2030-09-24T12:34:56Z",
  "duration": 120,
  "external_user_id": "432",
  "user_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "external_contact_id": "4534",
  "contact_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "from_number": "(555) 555-1234",
  "to_number": "(555) 555-5678",
  "incoming": true,
  "source": "Broker",
  "source_id": "80",
  "stage": "Agents",
  "stage_id": "60",
  "external_recording_id": "ext-123"
}
```

## Error Responses

**400 Bad Request** — The `identifier` path parameter is not a valid UUID, or the prefix does not match an accepted format.

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid identifier format"
}
```

**404 Not Found** — No call matching the provided identifier exists in your organization.

```json theme={null}
{
  "statusCode": 404,
  "message": "Call not found"
}
```