# File conversations: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/file-conversations
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 1.

## GET /v1/audio/{fileId}/conversations

Operation id: `list_file_conversations`

**List the conversations about a file**

Returns your conversations that were started on one file, newest activity first, so a file page can show the discussions about it. A conversation counts when it was created with the file's `audio_url`, under any of the addresses the same file has been known by. Deleted conversations are left out. Page with `cursor`: while `meta.has_more` is true, pass `meta.cursor` as `cursor` in the next request. A file with no conversations, a file that does not exist and a file that is not yours all answer an empty list. On success this route answers `{ data, meta }`, and `meta` carries counts but no `request_id`. `meta` here also has `cursor` and `has_more`. If the database is briefly unavailable the list is empty rather than an error.

Access: API key required; free and paid accounts. Cost: no token cost.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `fileId` | path | string | yes | The `audio_id` of one of your files. A trailing media extension such as `.wav` is ignored. |
| `cursor` | query | string | no | The `meta.cursor` of the previous page. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `[].conversation_id` | string | Identifier of the conversation. |
| `[].title` | string \| null | Title of the conversation, or null. |
| `[].updated_at` | number \| null | When the conversation last changed, in milliseconds since the Unix epoch. |

### Responses

200: A page of conversations, newest first.

```json
{
  "data": [
    {
      "conversation_id": "c3a9f1d2-7b46-4e80-9d15-2f6a8b0c4e71",
      "title": "Mix notes",
      "updated_at": 1791333870854
    }
  ],
  "meta": {
    "count": 1,
    "cursor": null,
    "has_more": false
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
FILEID="YOUR_FILEID"
curl "https://api.scarleta.ai/v1/audio/$FILEID/conversations" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```