POSThttps://core-api.heysadie.ai/transcriber-banks/{id}/full-call-runs
id candidateTranscriberId callIds calibrationTurns success data run organizationId bankId selection callCount estimate calls callerTurns audioSeconds estimatedCostUsd status analysisSampled error createdBy createdAt startedAt finishedAt metadata timestamp version path code message details field runId callId reasonStart a full-call run
Start a full-call run, to prove a candidate on whole calls before switching production to it. - Every caller line with audio bounds of the 1 to 10 asked calls becomes a turn; the assistant's lines are never replayed. Each turn's production attempt is the call's stored live text, and the candidate replays the line from the caller's channel, or the mixed track on a mono recording. - A line with a flag is scored against the flag's expected text. Any other line compares the candidate with production, and an LLM judge labels the lines where they differ. - `calibrationTurns` random turns also replay production, to measure how far replayed audio drifts from the live text (`totals.audioPathAgreement`). - Send an `Idempotency-Key` header, fixed per attempt to start a run. Keys are per organization and checked before anything else: a repeated key answers 201 with the run it first created, whatever the bank or body, and starts nothing. - One run per organization may be queued or running at a time. Next: poll GET /full-call-runs/:id, honoring `Retry-After`, until `run.status` is completed, cancelled or error. `progress` drives a progress bar. Errors: Checked in this order: 404 RESOURCE_NOT_FOUND when any asked call is not in the organization; 422 CALL_NOT_RUNNABLE naming the first asked call that cannot run and why (`details.callId`, `details.reason`); 404 RESOURCE_NOT_FOUND when the bank is not in the organization; 422 CANDIDATE_REQUIRED when no `candidateTranscriberId` was sent and the bank has no leader over the last 30 days; 422 NOT_A_BANK_CANDIDATE when `candidateTranscriberId` is not a live candidate of the bank. Then 409 RUN_ACTIVE when another run of the organization is queued or running (`details.runId`).
Try it in the API ExplorerExample request
curl -X POST "https://core-api.heysadie.ai/transcriber-banks/TRANSCRIBER_BANK_ID/full-call-runs" \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"candidateTranscriberId": "0199a1b2-aaaa-7bbb-8ccc-0000000000a1",
"callIds": [
"0199a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b",
"0199a1b3-0d1e-7f20-9a3b-4c5d6e7f8091"
],
"calibrationTurns": 20
}'Authentication
Authenticate with an API key in the Authorization header using the ApiKey scheme. See Authentication for how keys work and where to get them.
AuthorizationstringrequiredAPI key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.
X-Tenant-Idstring (uuid)optionalRequired when authenticating with an organization key: it selects the tenant the request acts on. Omit with tenant keys.
Request
Path parameters
idstringrequiredA live bank of the organization
Body application/json · required
candidateTranscriberIdstringoptionalOne of the bank's candidates. Defaults to the bank's leader over the last 30 days; with no leader over that window, send it or get 422 CANDIDATE_REQUIRED
callIdsstring[]required1 to 10 distinct calls of the organization, replayed in this order. Start from the call a line was flagged on and add others from GET /full-call-runs/eligible-calls. Each needs a recording, a caller line with audio bounds and a known live transcriber, else 422 CALL_NOT_RUNNABLE. A call outside the organization is a 404
calibrationTurnsstring (integer) | integeroptionalRandom turns on which production is also replayed, to measure replay against the live text (`totals.audioPathAgreement`). 0 to 200, default 20
Responses
successbooleanrequiredtrue on every 2xx
dataobjectoptionalThe result
Show 1 child properties
runobjectrequiredA full-call run: one candidate replayed on every caller line of up to 10 calls and compared with production
Show 15 child properties
idstringrequiredRun id
organizationIdstringrequiredThe organization that owns the run
bankIdstringrequiredThe bank the run belongs to
candidateTranscriberIdstringrequiredThe candidate replayed
selectionobjectrequiredThe calls asked for
Show 1 child properties
callIdsstring[]requiredThe calls the run replays, in the order they were asked for
calibrationTurnsstring (integer) | integerrequiredRandom turns asked for on which production is also replayed
callCountstring (integer) | integerrequiredCalls the run snapshotted
estimateobjectrequiredWhat the run replays and costs, as estimated at creation
Show 4 child properties
callsstring (integer) | integerrequiredSelected calls with a caller turn
callerTurnsstring (integer) | integerrequiredCaller lines with audio bounds; each becomes a turn
audioSecondsnumberrequiredAudio the worker replays: every turn through the candidate, plus the calibration sample through production
estimatedCostUsdnumberrequiredSTT cost in USD, 6 decimals
statusenumrequiredqueued: waiting for a worker. running: the candidate is replaying the turns. analyzing: the LLM judge is labeling the differing turns and writing patterns and a verdict. completed: done. cancelled: stopped by POST /full-call-runs/:id/cancel. error: failed, see `error`. queued, running and analyzing can still change; poll until completed, cancelled or error
"queued""running""analyzing""completed""cancelled""error"analysisSampledbooleanrequiredThe differing turns outnumbered what the analysis takes (2000), so it labeled a sample
errorstring | nullrequiredWhy the run failed. Null unless status is error
createdBystring | nullrequiredWho made it, as the creating request named them in an `X-On-Behalf-Of` header. Null when it sent none
createdAtstring (date-time) | string (date) | number | nullrequiredWhen it was created, UTC
startedAtstring (date-time) | string (date) | number | nullrequiredWhen its first job was dispatched to a worker, UTC
finishedAtstring (date-time) | string (date) | number | nullrequiredWhen it completed, failed or was cancelled, UTC
metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested
400VALIDATION_ERROR: a path id, query parameter or body field broke a rule; `details` lists each `field` and its `message`. A body with a missing field or a JSON type the schema does not allow answers 400 with code INTERNAL_SERVER_ERROR and no `details` instead, so branch on the status
successbooleanrequiredfalse on every error
errorobjectoptionalWhat went wrong: a stable `code` to branch on and a human-readable `message`
Show 3 child properties
codeenumrequiredA parameter or body field broke a rule
"VALIDATION_ERROR"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
detailsobject[]optionalOne entry per field that failed
Show 2 item properties
fieldstringrequiredThe offending field
messagestringrequiredThe rule it broke
metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested
401UNAUTHORIZED: no valid credentials, or a dashboard token that names no organization. Send `Authorization: ApiKey <organization API key>`
successbooleanrequiredfalse on every error
errorobjectoptionalWhat went wrong: a stable `code` to branch on and a human-readable `message`
Show 2 child properties
codeenumrequiredNo valid credentials
"UNAUTHORIZED"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested
403ORG_SCOPE_REQUIRED: transcriber testing is an organization feature. Use an organization API key without `X-Tenant-Id`, or a dashboard token scoped to the organization. A tenant API key, an organization key sent with `X-Tenant-Id` for one of its tenants, or a token carrying a tenant gets this 403. FORBIDDEN: an organization key sent `X-Tenant-Id` for a tenant outside its organization
successbooleanrequiredfalse on every error
errorobjectoptionalWhat went wrong: a stable `code` to branch on and a human-readable `message`
Show 2 child properties
codeenumrequiredORG_SCOPE_REQUIRED: the credentials carry a tenant scope. FORBIDDEN: an organization key sent `X-Tenant-Id` for a tenant outside its organization
"ORG_SCOPE_REQUIRED""FORBIDDEN"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested
404RESOURCE_NOT_FOUND: an id in the path, query or body names nothing in the caller's organization. `message` names what, e.g. "Transcriber bank not found"
successbooleanrequiredfalse on every error
errorobjectoptionalWhat went wrong: a stable `code` to branch on and a human-readable `message`
Show 2 child properties
codeenumrequiredAn id names nothing the caller can see
"RESOURCE_NOT_FOUND"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested
409RUN_ACTIVE: a run's state refuses the request; `details.runId` names the run
successbooleanrequiredfalse on every error
errorobjectoptionalWhat went wrong: a stable `code` to branch on and a human-readable `message`
Show 3 child properties
codeenumrequiredA run's state refuses the request
"RUN_ACTIVE"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
detailsobjectrequiredThe run in the way
Show 1 child properties
runIdstringrequiredThe run in the way
metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested
422CALL_NOT_RUNNABLE: an asked call cannot be replayed; `details` names the first such call and the reason. CANDIDATE_REQUIRED: no `candidateTranscriberId` was sent and the bank has no leader over the last 30 days. NOT_A_BANK_CANDIDATE: `candidateTranscriberId` is not a live candidate of the bank
successbooleanrequiredfalse on every error
errorobjectoptionalOne of three refusals, told apart by `code`
Show 8 properties across 3 possible shapes
codeenumrequiredNo candidate to replay
"CANDIDATE_REQUIRED"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
codeenumrequiredThe candidate is not the bank's
"NOT_A_BANK_CANDIDATE"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
detailsobjectrequiredThe transcriber refused
Show 1 child properties
candidateTranscriberIdstringrequiredNot a candidate of the bank, or deleted from the catalogue since it was added
codeenumrequiredAn asked call cannot be replayed
"CALL_NOT_RUNNABLE"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
detailsobjectrequiredThe call and why
Show 2 child properties
callIdstringrequiredThe first asked call that cannot run
reasonenumrequiredno_recording: the call has no recording. no_caller_audio: no caller line has audio bounds. transcriber_unknown: the call's live transcriber is unknown, so there is no production text to compare with
"no_recording""no_caller_audio""transcriber_unknown"metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested
500An unexpected server error
successbooleanrequiredfalse on every error
errorobjectoptionalWhat went wrong: a stable `code` to branch on and a human-readable `message`
Show 2 child properties
codeenumrequiredAn unexpected server failure
"INTERNAL_SERVER_ERROR"messagestringrequiredHuman-readable explanation. Do not parse it; branch on `code`
metadataobjectoptionalRequest metadata
Show 3 child properties
timestampstringrequiredWhen the server answered, ISO 8601 UTC
versionstringrequiredAPI version
pathstringoptionalThe URL that was requested