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

# List Recordings & Uploads Endpoint

> List every call recording and uploaded file in your Tuco workspace, newest first, with signed playback links. Beta endpoint, bearer-token auth.

> [!NOTE]
>
> This endpoint is in **beta**. The interface is stable enough to build on; we may add fields as it matures.

## Overview

Returns two separate lists for your workspace:

* **`recordings`** — audio from calls placed on your Tuco line, captured automatically.
* **`items`** — files *you* uploaded, via [Upload attachment](https://docs.tuco.ai/api-reference/upload-attachment.md) or the **Leads → Upload audio etc** tab.

Use this when you want everything in the workspace. To pull the calls made to one
specific lead, use [Get call recordings](https://docs.tuco.ai/api-reference/endpoint/get-recordings.md)
instead — that endpoint takes a phone number and returns full call timing.

***

## Making a request

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

```bash theme={null}
curl "https://app.tuco.ai/api/attachments/list?limit=20" \
  -H "Authorization: Bearer tuco_your_key"
```

### Query parameters

**limit** `number`

Max entries to return per list. Default `20`, min `1`, max `100`.

**cursor** `string`

Opaque cursor from a previous response's `nextCursor`, to page through **uploads**.

**recordingsCursor** `string`

Opaque cursor from a previous response's `recordingsNextCursor`, to page through
**recordings**. Recordings and uploads paginate independently — see
[Paging](#paging).

***

## Response

```json theme={null}
{
  "recordings": [
    {
      "url": "https://app.tuco.ai/api/attachments/crm-media/6aac0729....mp3?u=...&exp=...&sig=...",
      "name": "Call → +15145550123 · 3:40",
      "size": 878733,
      "uploadedAt": "2026-09-17T15:28:41.632Z",
      "pathname": "workspaces/org_.../recordings/6aac0729....mp3",
      "isAudio": true,
      "kind": "recording",
      "callId": "6aac072927e54a4003b72623",
      "toE164": "+15145550123",
      "fromE164": "+13025550999",
      "durationSec": 220
    }
  ],
  "recordingsNextCursor": null,
  "recordingsHasMore": false,
  "items": [
    {
      "url": "https://app.tuco.ai/api/attachments/crm-media/vn.m4a?u=...&exp=...&sig=...",
      "name": "vn.m4a",
      "size": 45056,
      "uploadedAt": "2026-09-18T10:02:11.000Z",
      "pathname": "workspaces/org_.../attachments/....m4a",
      "isAudio": true,
      "kind": "upload"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

**recordings** `array`

Call recordings, newest first.

**recording fields**

**url** `string`

Signed playback/download URL. See [Links expire](#links-expire).

**name** `string`

Display label, e.g. `Call → +15145550123 · 3:40`.

**size** `number`

File size in bytes.

**uploadedAt** `string`

When the call was answered; falls back to when it was requested, then to when the audio was stored.

**pathname** `string`

Internal storage path. Informational only.

**isAudio** `boolean`

Always `true` for recordings.

**kind** `string`

Always `recording`. Use this to tell the two lists apart if you merge them.

**callId** `string`

The call's ID — pass it to your own systems, or match it against [Get call recordings](https://docs.tuco.ai/api-reference/endpoint/get-recordings.md).

**toE164** `string`

Number that was called. `null` if the call record is unavailable.

**fromE164** `string`

Caller ID the lead saw. `null` if the call record is unavailable.

**durationSec** `number`

Talk time in seconds. `null` if the call record is unavailable.

**recordingsNextCursor** `string`

Cursor for the next page of recordings, or `null`.

**recordingsHasMore** `boolean`

Whether more recordings exist beyond this page.

**items** `array`

Files you uploaded, newest first.

**upload fields**

**url** `string`

Signed download URL.

**name** `string`

Original filename.

**size** `number`

File size in bytes.

**uploadedAt** `string`

When it was uploaded.

**pathname** `string`

Internal storage path. Informational only.

**isAudio** `boolean`

Whether the file is a supported audio type.

**kind** `string`

Always `upload`.

**nextCursor** `string`

Cursor for the next page of uploads, or `null`.

**hasMore** `boolean`

Whether more uploads exist beyond this page.

***

## Paging

Recordings and uploads are **paged independently**, each with its own cursor. Pass
`recordingsCursor` to advance recordings and `cursor` to advance uploads; you can
send both, either, or neither.

```bash theme={null}
# next page of recordings only
curl "https://app.tuco.ai/api/attachments/list?limit=20&recordingsCursor=CURSOR_FROM_LAST_RESPONSE" \
  -H "Authorization: Bearer tuco_your_key"
```

> [!NOTE]
>
> `limit` applies to **each** list, so `limit=20` can return up to 20 recordings *and*
> up to 20 uploads in one response.

## Links expire

> [!WARNING]
>
> Every `url` is a **signed link that expires**. Do not store it — keep the `callId`
> (for recordings) or `pathname`, and call this endpoint again when you need fresh
> links. The audio itself is kept indefinitely; only the link is time-limited.

Links from this endpoint are valid for **1 year**. Note that the same recording
requested via [Get call recordings](https://docs.tuco.ai/api-reference/endpoint/get-recordings.md) returns
a link valid for **30 days** — treat both as short-lived and re-fetch rather than
caching either.

## Format

Call recordings are **MP3, mono** — both sides of the conversation are mixed into a
single channel. Good for playback and transcription; not suited to separating the
speakers.

## Scope

You only ever see your own workspace's recordings and uploads. The API key you
authenticate with determines the workspace, and there is no parameter to query
another one.

***

## Errors

| HTTP | Meaning |
| - | - |
| 401 | Missing or invalid API key |
| 500 | Unexpected server error — the response body is `{ "error": "Could not load your uploads. Please try again." }` |


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