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

# Get Call Recordings Endpoint

> Fetch a lead's calls with timing details and the recording download URL, by phone number, using your API key.

<Info>This endpoint is in **beta**. The interface is stable enough to build on; we may add fields as it matures.</Info>

## Overview

Pull the calls placed to a given number in your workspace, newest first, each with
its timing details and a recording download URL. Use it to fetch **all** recordings
for a lead or just the **latest** one, straight into your own system.

***

## Making a request

* **Method**: `GET`
* **URL**: `https://app.tuco.ai/api/voice/recordings`
* **Headers**: `Authorization: Bearer tuco_...`

```bash theme={null}
curl "https://app.tuco.ai/api/voice/recordings?number=+13025550123&latest=true" \
  -H "Authorization: Bearer tuco_your_key"
```

### Query parameters

<ParamField query="number" type="string" required>
  The lead's phone number, E.164 (e.g. `+13025550123`). `to` is accepted as an alias.
</ParamField>

<ParamField query="latest" type="boolean">
  Return only the most recent call to that number.
</ParamField>

<ParamField query="withRecordingOnly" type="boolean">
  Return only calls that have a recording URL.
</ParamField>

<ParamField query="limit" type="number">
  Max calls to return. Default `20`, max `100`. Ignored when `latest=true`.
</ParamField>

***

## Response

Calls are returned newest first. Each entry includes timing details and the
recording download URL (recordings resolve after a call ends).

```json theme={null}
{
  "number": "+13025550123",
  "count": 2,
  "calls": [
    {
      "callId": "6a4ed2d5dec1b2d01a6f7656",
      "from": "+13025550999",
      "to": "+13025550123",
      "agent": "+13025550456",
      "surface": "api",
      "status": "billed",
      "requestedAt": "2026-07-09T00:12:03.000Z",
      "answeredAt": "2026-07-09T00:12:19.000Z",
      "endedAt": "2026-07-09T00:13:01.000Z",
      "durationSec": 42,
      "billedSec": 42,
      "billedCents": 1,
      "hangupCause": "normal_clearing",
      "recordingUrl": "https://.../recordings/6a4ed2d5....mp3"
    }
  ]
}
```

<ResponseField name="number" type="string">The number you queried.</ResponseField>
<ResponseField name="count" type="number">Number of calls returned.</ResponseField>

<ResponseField name="calls" type="array">
  The calls, newest first.

  <Expandable title="call fields">
    <ResponseField name="callId" type="string">Call record ID.</ResponseField>
    <ResponseField name="from" type="string">Caller ID the lead saw (your Tuco number).</ResponseField>
    <ResponseField name="to" type="string">The number called.</ResponseField>
    <ResponseField name="agent" type="string">Your rep's number (API calls only).</ResponseField>
    <ResponseField name="status" type="string">`requested` · `ringing` · `answered` · `billed` · `failed`.</ResponseField>
    <ResponseField name="requestedAt" type="string">When the call was created.</ResponseField>
    <ResponseField name="answeredAt" type="string">When it connected.</ResponseField>
    <ResponseField name="endedAt" type="string">When it ended.</ResponseField>
    <ResponseField name="durationSec" type="number">Talk time in seconds.</ResponseField>
    <ResponseField name="billedSec" type="number">Billed seconds.</ResponseField>
    <ResponseField name="hangupCause" type="string">Why the call ended.</ResponseField>
    <ResponseField name="recordingUrl" type="string">Download URL for the recording (`null` until the call ends and the recording is stored).</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  You only ever see calls in your own workspace. Recordings resolve a few seconds after
  a call ends; a `null` `recordingUrl` on a live or very recent call is expected.
</Note>

***

## Errors

| HTTP | `code`           | Meaning                                       |
| ---- | ---------------- | --------------------------------------------- |
| 401  | `UNAUTHORIZED`   | Missing or invalid API key                    |
| 400  | `MISSING_NUMBER` | `number` (the lead phone number) not provided |
| 500  | `INTERNAL_ERROR` | Unexpected server error                       |