---
title: "Get job status"
method: GET
path: "/v1/jobs/{job_id}"
tags: ["Jobs"]
---

# Get job status

`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`

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.

## Path parameters

- `job_id` string, uuid, required

## Headers

- `X-Claim-Token` string

## Response `200`

Job status.

- Job
  - `job_id` string, uuid, required
  - `status` 'queued' | 'processing' | 'done' | 'failed', required
  - `progress` number: Best-effort progress as a percentage, 0 to 100. A hint for a progress bar; branch on `status`.
  - `queue_position` integer: Recordings waiting ahead of this one while `queued` (not the ones already being transcribed); 0 otherwise.
  - `estimated_seconds` integer: 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_seconds` integer: While `processing`: seconds since processing started.
  - `remaining_seconds` integer: While `processing`: `estimated_seconds` minus `elapsed_seconds`, never below 0. Treat 0 as "almost done", not as finished; branch on `status`.
  - `overdue` boolean: `true` when processing has run past one and a half times the estimate. The job is still running.
  - `parts` object: Present while a long recording is transcribed in parts.
    - `current` integer: The part being transcribed now.
    - `total` integer
  - `audio_seconds_done` integer: Seconds of audio in the parts already transcribed, for recordings processed in parts.
  - `transcript_ready` boolean: `true` once the transcript can be fetched. It can turn `true` shortly before `status` becomes `done`, while the summary is still being written.
  - `filename` string, nullable
  - `audio_duration_seconds` number, nullable
  - `language` string, nullable
  - `source` 'upload' | 'url' | 'recording' | 'api': How the transcript was created. Defaults to `upload` for file submits and `url` for link submits.
  - `speech_detected` boolean: `false` when the audio holds no transcribable speech (music, noise, silence). The job still finishes as `done`, and no time is charged.
  - `speech_ratio` number: Fraction of the audio classified as speech.
  - `locked` boolean: `true` when the finished transcript needs credit on the account before it can be read in full.
  - `locked_code` string
  - `unlock_url` string, uri
  - `created_at` number: Unix epoch seconds.
  - `completed_at` number, nullable: Unix epoch seconds.
  - `error` string, 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.
  - `retryable` boolean: Present on a failed job. `true` when submitting the same request again can succeed. A failed job is never billed.
  - `error_help` object[]: Present on a failed job when a page shows how to fix it (for example `SOURCE_NOT_SHARED`: how to share a Google Drive file, or import it without sharing). Each item has a `label` and a `url`.
    - `label` string, required
    - `url` string, uri, required

## Other responses

- `304`: Not modified since the ETag you sent.
- `400`: Malformed request (e.g. `BAD_ID`, `BAD_URL`, `BAD_IDEMPOTENCY_KEY`).
- `401`: Missing or invalid API key, or the job needs an ownership proof (`X-Claim-Token`).
- `404`: Unknown job id, or a job that is not yours.
- `429`: Too many requests; retry with backoff (`RATE_LIMITED`, `QUOTA_EXCEEDED`).

---

[API](https://skmtc.dev/whipscribe/apis/whipscribe-api.md) · [All operations](https://skmtc.dev/whipscribe/apis/whipscribe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whipscribe/apis/whipscribe-api/revisions/cac5ec5d99d5?raw)