Uploading Recordings
The API upload endpoint is the same one the web app uses. Dropping a file onto the Files tab
and POSTing it to /api/files/ run through exactly the same server-side path, so a recording
uploaded by a script is transcribed — and, in a call project with automatic analysis, analyzed —
exactly as if it had been uploaded by hand. There is nothing API-specific to turn on.
Three resources are involved:
- File (
/api/files/) — the recording or transcript you upload. Once uploaded, transcription starts automatically. - Transcript (
/api/transcripts/) — the result, with metadata (language, duration, word count) and download links for SRT and DOCX. - Task (
/api/tasks/) — the background job that did the work (useful for retry).
All endpoints require either a session cookie or an API key — see Authentication. Every request needs the project’s numeric ID; Projects shows how to find it.
The flow at a glance
Section titled “The flow at a glance”Transcription — any project:
POST /api/files/— upload the recording. The response gives you afile.id, and transcription is enqueued automatically.- Poll
GET /api/files/{id}/untilstatusbecomestranscribed(success) orfailed. GET /api/transcripts/?uploaded_file={id}— read the resulting transcript record.GET /api/transcripts/{id}/download/?type=srt|docx— fetch a time-limited download URL for the file.
Automatic analysis — call projects:
- Configure the project once — enable automatic analysis and choose the analysis types. See Call projects: automatic analysis.
POST /api/files/— upload each recording with its agent, or send a CSV manifest first.- Poll
GET /calls/api/analysis-status/?project_id=…untilin_progressisfalse. - Read the results from the Call Reports API.
Steps 2–4 are all you repeat day to day.
POST /api/files/
Section titled “POST /api/files/”Upload a recording or a transcript. Recordings are transcribed automatically when the caller’s subscription has remaining minutes.
Auth: API key or session.
Content-Type: multipart/form-data
Form fields:
| Field | Required | Description |
|---|---|---|
project | yes | ID of the project the file belongs to. Must be visible to the caller — see Projects for how to look the ID up. |
file | yes | The recording (mp3, wav, m4a, flac, ogg, mp4, …), or an srt / vtt transcript you already have. |
file_type | yes | audio for recordings, or srt / vtt for transcripts, which skip transcription. (csv and xlsx are used for survey uploads.) |
agent_id, agent_name, agent_email | recommended in call projects | Who handled the call. With automatic analysis, leaving out all three returns a warning unless a manifest already lists the file. See Call Metadata. |
call_datetime, direction, ended_by, caller_number, campaign | no | The rest of the call metadata. Call projects only. |
Response (201 Created):
{ "id": 4217, "project": 312, "original_filename": "interview.wav", "file_type": "audio", "status": "transcribing", "duration_seconds": 1834.2, "error_reason": "", "asr_engine": "", "uploaded_at": "2026-05-17T14:02:11Z"}On call projects with automatic analysis on, the response can also include a warnings list.
Example:
curl -X POST https://app.uspeech.io/api/files/ \ -H "Authorization: Api-Key $USPEECH_KEY" \ -F "project=312" \ -F "file_type=audio" \ -F "file=@./interview.wav"import osimport requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
with open("interview.wav", "rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={"project": 312, "file_type": "audio"}, files={"file": ("interview.wav", fh, "audio/wav")}, timeout=300, )response.raise_for_status()file_id = response.json()["id"]import { openAsBlob } from 'node:fs';
const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };
const form = new FormData();form.set('project', '312');form.set('file_type', 'audio');form.set('file', await openAsBlob('./interview.wav'), 'interview.wav');
const response = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, // do not set Content-Type — FormData sets the boundary body: form,});if (!response.ok) throw new Error(await response.text());const fileId = (await response.json()).id;Sending call metadata
Section titled “Sending call metadata”In call projects, the same request can carry the call’s metadata — the agent, date and time, direction and campaign. Supplying metadata is what makes the report groupable by agent, direction, campaign and date. For bulk loads, send a CSV manifest before the recordings instead of per-file fields: rows are matched to files by name, including files uploaded later.
Example with call metadata:
curl -X POST https://app.uspeech.io/api/files/ \ -H "Authorization: Api-Key $USPEECH_KEY" \ -F "project=312" \ -F "file_type=audio" \ -F "file=@./call_001.mp3" \ -F "call_datetime=2026-06-15T09:12:00Z" \ -F "agent_id=A-06" \ -F "agent_name=Ana Diaz" \ -F "direction=inbound" \ -F "campaign=Retention"with open("call_001.mp3", "rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={ "project": project_id, "file_type": "audio", "call_datetime": "2026-06-15T09:12:00Z", "agent_id": "A-06", "agent_name": "Ana Diaz", "direction": "inbound", "campaign": "Retention", }, files={"file": ("call_001.mp3", fh, "audio/mpeg")}, timeout=300, )response.raise_for_status()file_id = response.json()["id"]print("uploaded", file_id)import { openAsBlob } from 'node:fs';
const form = new FormData();form.set('project', String(projectId));form.set('file_type', 'audio');form.set('call_datetime', '2026-06-15T09:12:00Z');form.set('agent_id', 'A-06');form.set('agent_name', 'Ana Diaz');form.set('direction', 'inbound');form.set('campaign', 'Retention');form.set('file', await openAsBlob('./call_001.mp3'), 'call_001.mp3');
const response = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, // do not set Content-Type — FormData sets the boundary body: form,});if (!response.ok) throw new Error(await response.text());const fileId = (await response.json()).id;console.log('uploaded', fileId);Re-uploading a call recording
Section titled “Re-uploading a call recording”A file uploaded under a name the project already has is treated as the same call — the new record replaces its predecessor rather than adding a second one. This makes retries safe: if a batch upload fails halfway, re-running it will not double-count calls in the report.
GET /api/files/{id}/
Section titled “GET /api/files/{id}/”Read a single file, including its current status.
Auth: API key or session.
Response (200 OK): same shape as the POST response above.
File status reference
Section titled “File status reference”| Status | Meaning |
|---|---|
uploaded | File saved, transcription not started — transcripts and other non-audio uploads, or audio uploaded when the subscription had no minutes left. |
transcribing | Transcription is in progress. |
transcribed | Transcription completed successfully. A Transcript record now exists. |
failed | Transcription failed. The error_reason field in this same response tells you why (audio_too_short, hallucinated_transcript, private_transcription_unavailable, or empty for other errors) — see Status Codes & Errors. |
analyzing, completed | Set when downstream analysis is running or finished (not relevant for the transcription-only flow). |
Polling pattern
Section titled “Polling pattern”file_id=4217while :; do resp=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \ -H "Authorization: Api-Key $USPEECH_KEY") status=$(echo "$resp" | jq -r .status) echo "$(date -u +%H:%M:%S) status=$status" case "$status" in transcribed) break ;; failed) echo "failed, reason: $(echo "$resp" | jq -r '.error_reason // "unknown"')" break ;; esac sleep 10doneimport time
while True: file_data = requests.get( f"{BASE_URL}/api/files/{file_id}/", headers=HEADERS, timeout=30 ).json() status = file_data["status"] print(f"status={status}") if status == "transcribed": break if status == "failed": raise RuntimeError(f"failed, reason: {file_data.get('error_reason') or 'unknown'}") time.sleep(10)const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
while (true) { const fileData = await fetch(`${BASE_URL}/api/files/${fileId}/`, { headers: HEADERS, }).then((r) => r.json()); console.log(`status=${fileData.status}`); if (fileData.status === 'transcribed') break; if (fileData.status === 'failed') { throw new Error(`failed, reason: ${fileData.error_reason || 'unknown'}`); } await sleep(10_000);}In call projects, the file also carries auto_analysis_error, the reason automatic analysis was
skipped for it — for example quota_exceeded when the subscription ran out of minutes.
Retrying a failed transcription
Section titled “Retrying a failed transcription”If a file ends up in failed, you can retry it via the Task API.
- Find the transcription Task for the file at
GET /api/tasks/?task_type=transcription(or follow the link from the web app). - Call
POST /api/tasks/{task_id}/retry/to re-queue it.
Don’t retry on terminal failures like audio_too_short — see Status Codes & Errors for the full list of error_reason values. Retrying is the right move for private_transcription_unavailable and for failures with an empty error_reason.
GET /api/transcripts/
Section titled “GET /api/transcripts/”List transcripts visible to the caller (scoped to projects they can see).
Auth: API key or session.
Response (200 OK): paginated list. Each item:
{ "id": 901, "uploaded_file": 4217, "language": "en", "duration_seconds": 1834.2, "word_count": 3120, "srt_path": "tenant/312/results/transcripts/interview.srt", "docx_path": "tenant/312/results/transcripts/interview.docx", "status": "completed", "error_reason": "", "asr_engine": "external", "created_at": "2026-05-17T14:05:33Z", "updated_at": "2026-05-17T14:08:47Z"}status here is queued → processing → completed | failed. When status is failed, error_reason holds a machine-readable cause (audio_too_short, hallucinated_transcript, private_transcription_unavailable) or is empty for other errors — see Status Codes & Errors.
asr_engine records which speech recognition service produced the transcript: external (the default provider) or private (USpeech-operated infrastructure, used when the project requires private transcription). It is also returned on the file resource, and stays empty until transcription completes.
GET /api/transcripts/{id}/
Section titled “GET /api/transcripts/{id}/”Retrieve a single transcript by ID. Same field shape as the list response.
curl https://app.uspeech.io/api/transcripts/901/ \ -H "Authorization: Api-Key $USPEECH_KEY"transcript = requests.get( f"{BASE_URL}/api/transcripts/901/", headers=HEADERS, timeout=30).json()const transcript = await fetch(`${BASE_URL}/api/transcripts/901/`, { headers: HEADERS,}).then((r) => r.json());If the transcript exists but isn’t visible to the caller, the response is 404 Not Found.
GET /api/transcripts/{id}/download/
Section titled “GET /api/transcripts/{id}/download/”Return a time-limited URL for the transcript artefact (SRT or DOCX). The URL points at private storage — use it from the same machine that received the response.
Auth: API key or session.
Query parameters:
| Param | Required | Description |
|---|---|---|
type | no | srt (default) or docx. |
Response (200 OK):
{ "download_url": "https://…/interview.srt?X-Amz-Signature=…"}If the requested artefact hasn’t been generated (e.g. the transcript failed), the response is 404 Not Found.
Example:
# Get the URL …url=$(curl -sS "https://app.uspeech.io/api/transcripts/901/download/?type=srt" \ -H "Authorization: Api-Key $USPEECH_KEY" | jq -r .download_url)
# … then download.curl -o interview.srt "$url"# Get the URL …url = requests.get( f"{BASE_URL}/api/transcripts/901/download/", headers=HEADERS, params={"type": "srt"}, timeout=30,).json()["download_url"]
# … then download. The URL is pre-signed, so it needs no auth header.with open("interview.srt", "wb") as fh: fh.write(requests.get(url, timeout=120).content)import { writeFile } from 'node:fs/promises';
// Get the URL …const { download_url: url } = await fetch( `${BASE_URL}/api/transcripts/901/download/?type=srt`, { headers: HEADERS },).then((r) => r.json());
// … then download. The URL is pre-signed, so it needs no auth header.const srt = await fetch(url).then((r) => r.arrayBuffer());await writeFile('interview.srt', Buffer.from(srt));Call projects: automatic analysis
Section titled “Call projects: automatic analysis”When a call project has automatic analysis enabled, every recording is analyzed as soon as it finishes transcribing — no separate “run analysis” call is needed. Uploads work exactly as described above; the sections below cover configuring the project, how calls are batched, and how to follow progress and read the results.
Configure automatic analysis
Section titled “Configure automatic analysis”Automatic analysis is configured on the project, via PATCH /api/projects/{id}/. You can do
this from the web app’s analysis wizard instead — the settings are the same either way.
Fields:
| Field | Type | Description |
|---|---|---|
auto_analysis_enabled | bool | Master switch. Analysis only happens when this is true. |
auto_analysis_types | list | Which analyses to run per call. One or more of calls_analysis_copc, calls_analysis_no_protocol, custom_questions. |
auto_analysis_questions | list of strings | The question set answered per call. Required when custom_questions is enabled. |
evaluation_rubric | int | ID of the rubric to score against. Required when calls_analysis_copc is enabled. |
auto_analysis_batch_size | int | Dispatch a batch once this many calls are waiting. Default 20, allowed range 1–20. |
auto_analysis_max_wait_seconds | int | Flush a partial batch once its oldest waiting call is this old. Default 300. |
Validation — the request is rejected with 400 when the configuration would produce
unusable runs:
- The project’s
audio_typeis notcall— automatic analysis is call-projects only. auto_analysis_typesis empty.calls_analysis_copcis requested without anevaluation_rubric.custom_questionsis requested without anyauto_analysis_questions.auto_analysis_batch_sizeis outside1–20.
Example — enable per-call analysis with no protocol plus two custom questions:
curl -X PATCH https://app.uspeech.io/api/projects/312/ \ -H "Authorization: Api-Key $USPEECH_KEY" \ -H "Content-Type: application/json" \ -d '{ "auto_analysis_enabled": true, "auto_analysis_types": ["calls_analysis_no_protocol", "custom_questions"], "auto_analysis_questions": ["Was a callback offered?", "Was the discount mentioned?"], "auto_analysis_batch_size": 20, "auto_analysis_max_wait_seconds": 300 }'import osimport requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}project_id = 312
response = requests.patch( f"{BASE_URL}/api/projects/{project_id}/", headers=HEADERS, json={ "auto_analysis_enabled": True, "auto_analysis_types": ["calls_analysis_no_protocol", "custom_questions"], "auto_analysis_questions": [ "Was a callback offered?", "Was the discount mentioned?", ], "auto_analysis_batch_size": 20, "auto_analysis_max_wait_seconds": 300, }, timeout=30,)response.raise_for_status()print(response.json()["auto_analysis_types"])const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };const projectId = 312;
const response = await fetch(`${BASE_URL}/api/projects/${projectId}/`, { method: 'PATCH', headers: { ...HEADERS, 'Content-Type': 'application/json' }, body: JSON.stringify({ auto_analysis_enabled: true, auto_analysis_types: ['calls_analysis_no_protocol', 'custom_questions'], auto_analysis_questions: ['Was a callback offered?', 'Was the discount mentioned?'], auto_analysis_batch_size: 20, auto_analysis_max_wait_seconds: 300, }),});if (!response.ok) throw new Error(await response.text());console.log((await response.json()).auto_analysis_types);GET /api/projects/{id}/ returns the same fields, so you can check the current configuration
before changing it.
How batching works
Section titled “How batching works”Calls are not analyzed one at a time — they are analyzed in small batches, which is why results appear in groups rather than one by one.
A batch for a given analysis type is dispatched when either condition is met:
auto_analysis_batch_sizecalls are waiting — the batch goes immediately.- The oldest waiting call reaches
auto_analysis_max_wait_seconds— the partial batch is flushed by a sweep that runs every 60 seconds.
So a partial batch is never stranded: with the defaults, a lone call uploaded at the end of the
day is analyzed within about five minutes. If you upload in large runs, lower
auto_analysis_max_wait_seconds only if you need results sooner than that — smaller batches
cost more per call.
Track progress
Section titled “Track progress”Two levels of visibility:
Per file — GET /api/files/{id}/ reports the transcription status (transcribing →
transcribed | failed) and an auto_analysis_error field that surfaces the reason automatic
analysis was skipped for that file, e.g. quota_exceeded when the subscription ran out of
minutes.
Per project — GET /calls/api/analysis-status/?project_id={id} is the endpoint the
dashboard itself polls:
{ "analysis_status": { "calls_analysis_no_protocol": { "completed": 57, "queued": 3 } }, "analyzed_calls": 57, "duplicate_uploads": 2, "in_progress": true, "reclustering": false, "last_analyzed_at": "2026-07-29T02:50:11.127124+00:00"}Poll it until in_progress is false, then fetch the report. See
Call Reports for the full field reference.
while :; do resp=$(curl -sS "https://app.uspeech.io/calls/api/analysis-status/?project_id=312" \ -H "Authorization: Api-Key $USPEECH_KEY") in_progress=$(echo "$resp" | jq -r .in_progress) echo "$(date -u +%H:%M:%S) analyzed=$(echo "$resp" | jq -r .analyzed_calls) in_progress=$in_progress" [ "$in_progress" = "false" ] && break sleep 30doneimport time
while True: status = requests.get( f"{BASE_URL}/calls/api/analysis-status/", headers=HEADERS, params={"project_id": project_id}, timeout=30, ).json() print(f"analyzed={status['analyzed_calls']} in_progress={status['in_progress']}") if not status["in_progress"]: break time.sleep(30)const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
while (true) { const status = await fetch( `${BASE_URL}/calls/api/analysis-status/?project_id=${projectId}`, { headers: HEADERS }, ).then((r) => r.json()); console.log(`analyzed=${status.analyzed_calls} in_progress=${status.in_progress}`); if (!status.in_progress) break; await sleep(30_000);}Read the results
Section titled “Read the results”Once in_progress is false, the analyzed calls are available through the
Call Reports API:
GET /calls/api/report/?project_id={id}— the aggregated QA reportGET /calls/api/calls/?project_id={id}— the per-call explorerGET /calls/api/custom-questions/?project_id={id}— per-call answers to your custom questionsGET /calls/api/report/pdf/?project_id={id}— the PDF export
End-to-end examples
Section titled “End-to-end examples”Transcribe a recording and download the SRT
Section titled “Transcribe a recording and download the SRT”# 1. Uploadresp=$(curl -sS -X POST https://app.uspeech.io/api/files/ \ -H "Authorization: Api-Key $USPEECH_KEY" \ -F "project=312" -F "file_type=audio" \ -F "file=@./interview.wav")file_id=$(echo "$resp" | jq -r .id)
# 2. Pollwhile :; do resp=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \ -H "Authorization: Api-Key $USPEECH_KEY") status=$(echo "$resp" | jq -r .status) [ "$status" = "transcribed" ] && break [ "$status" = "failed" ] && { echo "transcription failed: $(echo "$resp" | jq -r '.error_reason // "unknown"')" exit 1 } sleep 10done
# 3. Find the transcript and download SRTtranscript_id=$(curl -sS "https://app.uspeech.io/api/transcripts/?uploaded_file=${file_id}" \ -H "Authorization: Api-Key $USPEECH_KEY" | jq -r '.results[0].id')
url=$(curl -sS "https://app.uspeech.io/api/transcripts/${transcript_id}/download/?type=srt" \ -H "Authorization: Api-Key $USPEECH_KEY" | jq -r .download_url)
curl -o interview.srt "$url"import osimport time
import requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
# 1. Uploadwith open("interview.wav", "rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={"project": 312, "file_type": "audio"}, files={"file": ("interview.wav", fh, "audio/wav")}, timeout=300, )response.raise_for_status()file_id = response.json()["id"]
# 2. Pollwhile True: file_data = requests.get( f"{BASE_URL}/api/files/{file_id}/", headers=HEADERS, timeout=30 ).json() if file_data["status"] == "transcribed": break if file_data["status"] == "failed": raise SystemExit( f"transcription failed: {file_data.get('error_reason') or 'unknown'}" ) time.sleep(10)
# 3. Find the transcript and download SRTtranscripts = requests.get( f"{BASE_URL}/api/transcripts/", headers=HEADERS, params={"uploaded_file": file_id}, timeout=30,).json()transcript_id = transcripts["results"][0]["id"]
url = requests.get( f"{BASE_URL}/api/transcripts/{transcript_id}/download/", headers=HEADERS, params={"type": "srt"}, timeout=30,).json()["download_url"]
with open("interview.srt", "wb") as fh: fh.write(requests.get(url, timeout=120).content)import { openAsBlob } from 'node:fs';import { writeFile } from 'node:fs/promises';
const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 1. Uploadconst form = new FormData();form.set('project', '312');form.set('file_type', 'audio');form.set('file', await openAsBlob('./interview.wav'), 'interview.wav');
const upload = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, body: form,});if (!upload.ok) throw new Error(await upload.text());const fileId = (await upload.json()).id;
// 2. Pollwhile (true) { const fileData = await fetch(`${BASE_URL}/api/files/${fileId}/`, { headers: HEADERS, }).then((r) => r.json()); if (fileData.status === 'transcribed') break; if (fileData.status === 'failed') { throw new Error(`transcription failed: ${fileData.error_reason || 'unknown'}`); } await sleep(10_000);}
// 3. Find the transcript and download SRTconst transcripts = await fetch( `${BASE_URL}/api/transcripts/?uploaded_file=${fileId}`, { headers: HEADERS },).then((r) => r.json());const transcriptId = transcripts.results[0].id;
const { download_url: url } = await fetch( `${BASE_URL}/api/transcripts/${transcriptId}/download/?type=srt`, { headers: HEADERS },).then((r) => r.json());
await writeFile('interview.srt', Buffer.from(await fetch(url).then((r) => r.arrayBuffer())));Load a batch of calls into a call project
Section titled “Load a batch of calls into a call project”Configure the project, send the call metadata, upload a folder of recordings, wait for analysis, and fetch the report.
The metadata step comes first because automatic analysis needs each call’s agent as soon as the call arrives. There are two ways to supply it, and you can mix them freely:
- Per file at upload, as extra form fields on
POST /api/files/— best when your system already knows the details of each call as it uploads it. This is what the call metadata example above shows. - Per project, as a CSV manifest on
POST /api/projects/{id}/call-manifest/— best for bulk loads. Rows are matched to files by name, and rows that don’t match anything yet are kept and applied to files uploaded later. Send it before the recordings, with an agent in every row.
The example below uses the manifest, since it suits uploading a whole folder at once. See Call Metadata for the full field reference, the accepted date formats, and how to correct metadata after the fact.
#!/usr/bin/env bashset -euo pipefail
BASE_URL="https://app.uspeech.io"AUTH="Authorization: Api-Key ${USPEECH_KEY}"project_id=312
# 1. Enable automatic analysiscurl -sS -X PATCH "${BASE_URL}/api/projects/${project_id}/" \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"auto_analysis_enabled": true, "auto_analysis_types": ["calls_analysis_no_protocol"]}' \ > /dev/null
# 2. Send the call metadata for the whole batch first, so each upload finds its agent.# calls_june.csv: filename,call_datetime,agent_id,agent_name,direction,campaigncurl -sS -X POST "${BASE_URL}/api/projects/${project_id}/call-manifest/" \ -H "$AUTH" -F "file=@./calls_june.csv" \ | jq -r '"\(.matched) matched, \(.unmatched | length) waiting for their file"'
# 3. Upload every recording in ./calls/for path in ./calls/*.mp3; do curl -sS -X POST "${BASE_URL}/api/files/" \ -H "$AUTH" \ -F "project=${project_id}" \ -F "file_type=audio" \ -F "file=@${path}" \ | jq -r '"uploaded \(.original_filename) -> \(.id)", (.warnings[]? | "warning: \(.code): \(.detail)")'done
# 4. Wait for analysis to settlewhile :; do resp=$(curl -sS "${BASE_URL}/calls/api/analysis-status/?project_id=${project_id}" -H "$AUTH") [ "$(echo "$resp" | jq -r .in_progress)" = "false" ] && break sleep 30done
# 5. Fetch the reportcurl -sS "${BASE_URL}/calls/api/report/?project_id=${project_id}" -H "$AUTH" > report.jsonecho "report written to report.json"import osimport timefrom pathlib import Path
import requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}project_id = 312
# 1. Enable automatic analysisrequests.patch( f"{BASE_URL}/api/projects/{project_id}/", headers=HEADERS, json={ "auto_analysis_enabled": True, "auto_analysis_types": ["calls_analysis_no_protocol"], }, timeout=30,).raise_for_status()
# 2. Send the call metadata for the whole batch first, so each upload finds its agent.# calls_june.csv: filename,call_datetime,agent_id,agent_name,direction,campaignwith open("calls_june.csv", "rb") as fh: manifest = requests.post( f"{BASE_URL}/api/projects/{project_id}/call-manifest/", headers=HEADERS, files={"file": ("calls_june.csv", fh, "text/csv")}, timeout=120, )manifest.raise_for_status()result = manifest.json()print(f"{result['matched']} matched, {len(result['unmatched'])} waiting for their file")
# 3. Upload every recording in ./calls/for path in sorted(Path("calls").glob("*.mp3")): with path.open("rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={"project": project_id, "file_type": "audio"}, files={"file": (path.name, fh, "audio/mpeg")}, timeout=300, ) response.raise_for_status() body = response.json() print(f"uploaded {path.name} -> {body['id']}") for warning in body.get("warnings", []): print(f"warning: {warning['code']}: {warning['detail']}")
# 4. Wait for analysis to settlewhile True: status = requests.get( f"{BASE_URL}/calls/api/analysis-status/", headers=HEADERS, params={"project_id": project_id}, timeout=30, ).json() if not status["in_progress"]: break time.sleep(30)
# 5. Fetch the reportreport = requests.get( f"{BASE_URL}/calls/api/report/", headers=HEADERS, params={"project_id": project_id}, timeout=60,).json()print(f"{report['headline']['total_calls']} calls in the report")import { readdir } from 'node:fs/promises';import { openAsBlob } from 'node:fs';
const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };const projectId = 312;const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 1. Enable automatic analysisawait fetch(`${BASE_URL}/api/projects/${projectId}/`, { method: 'PATCH', headers: { ...HEADERS, 'Content-Type': 'application/json' }, body: JSON.stringify({ auto_analysis_enabled: true, auto_analysis_types: ['calls_analysis_no_protocol'], }),});
// 2. Send the call metadata for the whole batch first, so each upload finds its agent.// calls_june.csv: filename,call_datetime,agent_id,agent_name,direction,campaignconst manifestForm = new FormData();manifestForm.set('file', await openAsBlob('./calls_june.csv'), 'calls_june.csv');
const manifest = await fetch(`${BASE_URL}/api/projects/${projectId}/call-manifest/`, { method: 'POST', headers: HEADERS, body: manifestForm,});if (!manifest.ok) throw new Error(await manifest.text());const { matched, unmatched } = await manifest.json();console.log(`${matched} matched, ${unmatched.length} waiting for their file`);
// 3. Upload every recording in ./calls/const names = (await readdir('calls')).filter((name) => name.endsWith('.mp3'));for (const name of names) { const form = new FormData(); form.set('project', String(projectId)); form.set('file_type', 'audio'); form.set('file', await openAsBlob(`calls/${name}`), name);
const response = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, body: form, }); if (!response.ok) throw new Error(`${name}: ${await response.text()}`); const { id, warnings = [] } = await response.json(); console.log(`uploaded ${name} -> ${id}`); for (const warning of warnings) console.log(`warning: ${warning.code}: ${warning.detail}`);}
// 4. Wait for analysis to settlewhile (true) { const status = await fetch( `${BASE_URL}/calls/api/analysis-status/?project_id=${projectId}`, { headers: HEADERS }, ).then((r) => r.json()); if (!status.in_progress) break; await sleep(30_000);}
// 5. Fetch the reportconst report = await fetch( `${BASE_URL}/calls/api/report/?project_id=${projectId}`, { headers: HEADERS },).then((r) => r.json());console.log(`${report.headline.total_calls} calls in the report`);Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause |
|---|---|
A file stays uploaded | Transcription did not start, usually because the subscription had no minutes left at upload time. |
A file ends up failed | error_reason says why. Retry only when it is empty or private_transcription_unavailable — see Retrying a failed transcription. |
File reaches transcribed but nothing is ever analyzed | auto_analysis_enabled is false, or auto_analysis_types is empty. Check GET /api/projects/{id}/. |
auto_analysis_error is quota_exceeded | The subscription ran out of minutes. Analysis is skipped, not retried automatically. |
The upload response has a warnings entry with code call_metadata_missing | Automatic analysis is on and the upload has no agent, so the report shows a guessed name. Send agent_id, agent_name or agent_email, or upload a manifest listing the file. |
400 on the upload with a metadata field in the body | The project is not a call project, or file_type is not audio/srt/vtt. |
400 when enabling automatic analysis | A rubric is missing for COPC, questions are missing for custom_questions, or the batch size is outside 1–20. |
| Report call count is lower than the number of files uploaded | Re-uploaded filenames replace the earlier call. duplicate_uploads in the analysis-status response counts them. |
unanalyzed_calls in the report is above 0 | Those calls were transcribed while automatic analysis was off; enabling it does not reach back to them. Analyze them once with a manual analysis. |
See Status Codes & Errors for the full list of response codes.