Recordings

Manage recordings and transcriptions.

List Recordings

GET /v1/recordings

Retrieve a paginated list of recordings.

Query Parameters

Parameter	Type	Required	Description	Default
`page`	integer	No	Page number (0-indexed). See Pagination	0
`limit`	integer	No	Results per page (max: 100). See Pagination	50
`status`	string	No	Filter by status: `transcribed`, `processing`, `failed`	-
`date_from`	string	No	Filter by start date (ISO 8601), e.g. `2025-10-01`	-
`date_to`	string	No	Filter by end date (ISO 8601), e.g. `2025-10-31`	-

See also: Filtering best practices

Request

Python
Node.js
cURL

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

# List all recordings
recordings = client.recordings.list(limit=10)

for record in recordings:
    print(record.id)

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function listRecordings() {
  const recordings = await client.recordings.list({ limit: 10 });

  for (const record of recordings.data) {
    console.log(record.id);
  }
}

curl -X GET "https://api.vocafuse.com/v1/recordings?limit=10" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

{
  "recordings": [
    {
      "id": "3d219a45-af16-4e2f-b018-dd8e44b4cf12",
      "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
      "user_id": null,
      "original_filename": "recording-2025-10-06T17-33-30-532Z.webm",
      "s3_key": "63f8fa32-0740-4263-9bed-578156b3526b/3d219a45-af16-4e2f-b018-dd8e44b4cf12.webm",
      "s3_bucket": "async-api-audio-dev-227647310470",
      "duration_seconds": 16.45,
      "file_size_bytes": 252287,
      "audio_format": "webm",
      "sample_rate": null,
      "channels": 1,
      "bit_rate": null,
      "audio_codec": null,
      "status": "transcribed",
      "features": null,
      "client_ip": null,
      "user_agent": null,
      "upload_source": null,
      "custom_tags": null,
      "created_at": "2025-10-06T17:33:31",
      "updated_at": "2025-10-06T17:33:45",
      "processed_at": null,
      "uri": "/v1/recordings/3d219a45-af16-4e2f-b018-dd8e44b4cf12"
    }
  ],
  "uri": "/v1/recordings?page=0&limit=10",
  "first_page_uri": "/v1/recordings?page=0&limit=10",
  "next_page_uri": "/v1/recordings?page=1&limit=10",
  "previous_page_uri": null,
  "page": 0,
  "page_size": 10,
  "total": 10
}

The response includes pagination metadata for navigating through results.

Response Fields

Field	Type	Description
`id`	string	Unique recording identifier
`tenant_id`	string	Your VocaFuse account identifier
`user_id`	string	End user identifier (from JWT token identity)
`original_filename`	string	Original file name from upload
`duration_seconds`	number	Recording duration in seconds
`file_size_bytes`	integer	File size in bytes
`audio_format`	string	Audio format (webm, mp3, ogg, wav)
`status`	string	Processing status (see below)
`custom_tags`	object \| null	Optional app-provided tags (string → string) for correlating this recording with your app context
`created_at`	string	ISO 8601 timestamp when created
`updated_at`	string	ISO 8601 timestamp of last update
`uri`	string	API endpoint for this recording

custom_tags

custom_tags lets you attach lightweight app context at upload time (e.g. action type, job ID, customer ID). These tags are stored on the Recording object and are also included in webhook payloads so you can route processing deterministically.

Constraints (v1):

Max keys: 10
Key: 1–32 chars, allowed characters: A–Z a–z 0–9 _ -
Value: string up to 128 chars (no control characters)
Total serialized size: ≤ 1024 bytes
Non‑PII only (use opaque IDs; do not include names/phones/addresses/transcripts)

Example:

{
  "custom_tags": {
    "actionType": "CreateReport",
    "jobId": "job_123",
    "customerId": "cust_456"
  }
}

Status Values

Status	Description
`processing`	Recording is being transcribed
`transcribed`	Transcription completed successfully
`failed`	Processing failed

Get Recording

GET /v1/recordings/{recording_id}

Retrieve details of a specific recording.

Path Parameters

Parameter	Type	Description
`recording_id`	string	The recording ID (e.g., `rec_abc123`)

Request

Python
Node.js
cURL

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

recording = client.recordings.get('rec_123')

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function getRecording() {
  const recording = await client.recordings('rec_123').get();
  console.log(recording.data);
}

curl -X GET "https://api.vocafuse.com/v1/recordings/{recording_id}" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

{
  "id": "606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "user_id": null,
  "original_filename": "recording.mp3",
  "s3_key": "63f8fa32-0740-4263-9bed-578156b3526b/606cf8f5-b294-4b9c-ad0e-3afeb99c6804.mp3",
  "s3_bucket": "async-api-audio-dev-227647310470",
  "duration_seconds": 5.0,
  "file_size_bytes": 235790,
  "audio_format": "mp3",
  "sample_rate": null,
  "channels": 1,
  "bit_rate": null,
  "audio_codec": null,
  "status": "transcribed",
  "features": null,
  "client_ip": null,
  "user_agent": null,
  "upload_source": null,
  "custom_tags": null,
  "created_at": "2025-08-28T15:54:31",
  "updated_at": "2025-08-28T15:54:34",
  "processed_at": null,
  "uri": "/v1/recordings/606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "subresource_uris": {
    "transcription": "/v1/recordings/606cf8f5-b294-4b9c-ad0e-3afeb99c6804/transcription"
  }
}

Get Transcription

GET /v1/recordings/{recording_id}/transcription

Retrieve the transcription for a completed recording.

Request

Python
Node.js
cURL

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

transcription = client.recordings(
  'rec_123'
).transcription.get()

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function getTranscription() {
  const transcription = await client.recordings('rec_123').transcription.get();
  console.log(transcription.data.text);
}

curl -X GET "https://api.vocafuse.com/v1/recordings/{recording_id}/transcription" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

{
  "id": "b585a2af-56b3-435d-a51c-024d4cccfe0f",
  "recording_id": "606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "text": "This is an audio recording test to be uploaded to my API. I'm playing some music in the background which might provide a more thorough test.",
  "confidence": 0.95,
  "language": "english",
  "provider": "openai",
  "model": "whisper-1",
  "processing_duration_ms": 1367,
  "words": "[]",
  "created_at": "2025-08-28T15:54:34",
  "updated_at": "2025-08-28T15:54:34",
  "uri": "/v1/recordings/606cf8f5-b294-4b9c-ad0e-3afeb99c6804/transcription"
}

warning

Not Ready Error: Returns 404 with error code TRANSCRIPTION_NOT_READY if transcription is still processing. Use webhooks instead of polling.

Delete Recording

DELETE /v1/recordings/{recording_id}

Delete a recording and its transcription.

Request

Python
Node.js
cURL

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

client.recordings('rec_123').delete()

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function deleteRecording() {
  await client.recordings('rec_123').delete();
}

curl -X DELETE "https://api.vocafuse.com/v1/recordings/{recording_id}" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response:

Status Code: 204 No Content

No response body is returned for successful deletions.

List Recordings​

Query Parameters​

Request​

Response​

Response Fields​

custom_tags​

Status Values​

Get Recording​

Path Parameters​

Request​

Response​

Get Transcription​

Request​

Response​

Delete Recording​

Request​

Response:​

List Recordings

Query Parameters

Request

Response

Response Fields

custom_tags

Status Values

Get Recording

Path Parameters

Request

Response

Get Transcription

Request

Response

Delete Recording

Request

Response: