Jobs

Get job status

Lightweight poll; a 3-second interval while the job is queued or processing is fine. Supports If-None-Match (304). Check locked before fetching the transcript.

get/v1/jobs/{job_id}

Request

  • Base URL: https://whipscribe.com/api
  • URL: https://whipscribe.com/api/v1/jobs/{job_id}
  • Auth: API key in header X-API-Key

Path parameters

job_idstring uuid required
Example:35f4be54-aa3e-4adc-85b7-b44f284d1fc3

The job id returned on submit.

Headers

X-Claim-Tokenstring

Proves ownership of a job submitted without a user identity. The submit response returns it as claim_token.

Response

Job status.

job_idstring uuid required
status'queued' | 'processing' | 'done' | 'failed' required
progressnumber

Best-effort progress as a percentage, 0 to 100. A hint for a progress bar; branch on status.

queue_positioninteger

Recordings waiting ahead of this one while queued (not the ones already being transcribed); 0 otherwise.

estimated_secondsinteger

While queued or processing: expected seconds from the start of processing until the transcript exists. Four jobs in five finish inside it. Absent until the length or size of the media is known.

estimate_basis'duration' | 'size'

duration when the estimate uses the measured audio length; size when the length is still a guess from the file size.

elapsed_secondsinteger

While processing: seconds since processing started.

remaining_secondsinteger

While processing: estimated_seconds minus elapsed_seconds, never below 0. Treat 0 as "almost done", not as finished; branch on status.

overdueboolean

true when processing has run past one and a half times the estimate. The job is still running.

audio_seconds_doneinteger

Seconds of audio in the parts already transcribed, for recordings processed in parts.

transcript_readyboolean

true once the transcript can be fetched. It can turn true shortly before status becomes done, while the summary is still being written.

filenamestring nullable
audio_duration_secondsnumber nullable
languagestring nullable
source'upload' | 'url' | 'recording' | 'api'

How the transcript was created. Defaults to upload for file submits and url for link submits.

speech_detectedboolean

false when the audio holds no transcribable speech (music, noise, silence). The job still finishes as done, and no time is charged.

speech_rationumber

Fraction of the audio classified as speech.

lockedboolean

true when the finished transcript needs credit on the account before it can be read in full.

locked_codestring
unlock_urlstring uri
created_atnumber

Unix epoch seconds.

completed_atnumber nullable

Unix epoch seconds.

errorstring nullable

On a failed job: one sentence a person can read. null otherwise.

error_code'SERVICE_UNAVAILABLE' | 'PROCESSING_STALLED' | 'PROCESSING_TIMEOUT' | 'NO_AUDIO' | 'SOURCE_NOT_SHARED' | 'SOURCE_SIGN_IN_REQUIRED' | 'LIVE_STREAM_UNSUPPORTED' | 'SOURCE_PROTECTED' | 'SOURCE_TOO_LARGE' | 'SOURCE_RATE_LIMITED' | 'SOURCE_UNAVAILABLE' | 'SOURCE_UNSUPPORTED' | 'SOURCE_ACCESS_DENIED' | 'SOURCE_UNREACHABLE' | 'SERVICE_ERROR'

Present on a failed job. Stable code for why it failed. SOURCE_* codes are about the link you submitted; NO_AUDIO is about the file.

retryableboolean

Present on a failed job. true when submitting the same request again can succeed. A failed job is never billed.

Example response

{
  "job_id": "35f4be54-aa3e-4adc-85b7-b44f284d1fc3",
  "status": "processing",
  "progress": 42,
  "audio_duration_seconds": 967,
  "language": "en",
  "source": "api",
  "locked": false,
  "error": null
}

Changes

No recorded changes to this operation across all 1 revision of this API.