Get a Job
Get a job's status and, once the job completes, its transcript. Use it to poll a job, to recover a result you missed, or to fetch a transcript as SRT or VTT.
Endpoint
GET https://api.speechischeap.com/v2/jobs/:job_id
Don't add a trailing slash. A request to /v2/jobs/:job_id/ returns 404 Not Found.
Authentication
None. This request needs no API key. Anyone with a job ID can read that job, so keep job IDs private.
Request
| Parameter | Type | Default | Description |
|---|---|---|---|
job_id | string | Required | The job ID in the URL path, such as 00000000-1111-7222-b333-444444444444-sic. |
output_format | string | "" | A query parameter. Returns a completed job's transcript as srt, vtt, or webvtt (an alias for vtt) instead of JSON. The API ignores it for a job that isn't COMPLETED, and returns JSON. See SRT and VTT Output. |
Example Requests
Get a Job as JSON
curl https://api.speechischeap.com/v2/jobs/00000000-1111-7222-b333-444444444444-sic
Get a Completed Job as SRT
curl 'https://api.speechischeap.com/v2/jobs/00000000-1111-7222-b333-444444444444-sic?output_format=srt'
Response
The API uses standard HTTP status codes to indicate the outcome of your request.
| Status Code | Description |
|---|---|
| 200 OK | The job exists. The body depends on its status. |
| 400 Bad Request | output_format isn't srt, vtt, or webvtt. The API checks it only for a completed job. |
| 404 Not Found | No job has this ID, or the path ends with a slash. |
| 500 Internal Server Error | The API couldn't read the job. Request it again. |
Pending Job Response
While the job is queued or running:
{
"id": "00000000-1111-7222-b333-444444444444-sic",
"output": {},
"status": "PENDING"
}
Completed Job Response
When the transcription is complete, the body holds the full result. See Output and Add-ons for every field and for the SRT and VTT formats.
{
"id": "00000000-1111-7222-b333-444444444444-sic",
"output": {
"duration": 24.512,
"request": {
"can_label_audio": false,
"can_parse_speakers": false,
"can_parse_words": false,
"can_stream_output": false,
"input_url": "https://example.com/audio-file.mp3",
"is_split_channel": false,
"language": null,
"minimum_confidence": 0.5,
"segment_duration": 30
},
"segments": [
{
"confidence": 0.988,
"end": 7.296,
"id": 1,
"language": "en (99.60%)",
"processing_duration_in_s": 0.029,
"start": 0,
"text": "Imagine staring at a massive hard drive filled with gigabytes of raw video files.",
"words": []
}
]
},
"status": "COMPLETED"
}
Failed Job Response
{
"id": "00000000-1111-7222-b333-444444444444-sic",
"output": {},
"status": "FAILED"
}
This response doesn't include the reason. It reaches only the job's webhook, as output.error, so set a webhook_url if you need it. See Failures After a Job Is Accepted for the common reasons. Jobs paid with x402 also report output.error here.
Canceled Job Response
{
"id": "00000000-1111-7222-b333-444444444444-sic",
"output": {},
"status": "CANCELED"
}
Private Jobs
For a job created with is_private, request.input_url is https://speechischeap.com/redacted. Twelve hours after the job completes, segments becomes an empty array:
{
"output": {
"request": {
"input_url": "https://speechischeap.com/redacted"
},
"segments": []
}
}
The rest of the response is unchanged. The webhook sent when the job completes still carries the full transcript, so protect your webhook endpoint.
Polling
To wait for a job without a webhook, get it every few seconds until its status is COMPLETED, FAILED, or CANCELED. The response doesn't report progress, and processing time grows with the length of the audio. See the measured processing times to choose a timeout. To get progress and segments as they're transcribed, create the job with can_stream_output instead. Treat a 500 while polling as temporary. Wait, then request the job again.
Poll From a Script
This script creates a job, polls it until it finishes, and prints the transcript. It needs curl and jq, and reads the key from SPEECHISCHEAP_API_KEY. It gives up after three failed requests in a row.
#!/usr/bin/env bash
set -euo pipefail
API=https://api.speechischeap.com/v2/jobs
# Create the job.
id=$(curl --silent --show-error --fail-with-body --request POST "$API/" \
--header "Authorization: Bearer $SPEECHISCHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"input_url": "https://example.com/audio-file.mp3"}' | jq -r .id)
# Poll every five seconds for up to 30 minutes.
deadline=$((SECONDS + 1800))
failures=0
while :; do
if job=$(curl --silent --show-error --fail-with-body "$API/$id"); then
failures=0
status=$(jq -r .status <<<"$job")
case $status in
COMPLETED) break ;;
FAILED | CANCELED) echo "Job ended with status $status" >&2; exit 1 ;;
esac
elif ((++failures >= 3)); then
echo 'Polling failed three times in a row' >&2
exit 1
fi
if ((SECONDS > deadline)); then echo 'Timed out waiting for the job' >&2; exit 2; fi
sleep 5
done
jq -r '.output.segments[].text' <<<"$job"
Run in CI
- Store the API key as a CI secret instead of in code, and check it before you start work.
- Exit with an error on
FAILEDorCANCELED, as the script does. A polledFAILEDjob doesn't include the error message, which reaches only the job's webhook. - Scale the timeout to the audio length. The measured processing times show how long jobs take.
- Anyone with a job ID can read the job, so don't print job IDs in public build logs. See Keep Job IDs Private.
- To transcribe a file from the build instead of a URL, use Upload a File. Its last event contains the job
idto poll. - For short clips, the Edge API returns the transcript in the same response, with no polling. See How to Transcribe.
Keep Job IDs Private
Getting a job doesn't require an API key. That's on purpose: some customers share a job's URL to share its transcript, without building their own sharing setup, such as pre-signed URLs. Job IDs are unguessable, but anyone who has one can read the job's status, transcript, and input_url, so keeping them private is up to you. Treat job IDs like secrets:
- Don't put job IDs in public URLs, logs, or client-side code.
- Create sensitive jobs with
is_private. See Private Jobs.
Errors
Errors have a plain-text body, and the most likely are 404 Not Found, which is a generic message, and Invalid output_format specified. See Jobs API errors for each one.