Jobs API

Used primarily by the SDK after /upload/complete to wait for a result, retrieve a job by id, or list recent jobs. These are the real user-cluster job endpoints.

Retrieve a job

GET/api/v1/jobs/{job_id}

Returns a job's current status plus a freshly-generated download_url once it has completed — valid even long after the original upload response. Backs the SDK's get_job_status / getJobStatus / GetJobStatus / GetJobStatusAsync and get_transcript methods.

bash

curl "https://api.speechrevolutions.com/api/v1/jobs/$JOB_ID" \
  -H "X-API-Key: $SPEECHREVOLUTIONS_API_KEY"

Response (JobStatusResponse):

json

{
  "job_id": "…",
  "status": "completed",          // processing | completed | failed
  "download_url": "https://…",    // present when status is "completed"
  "failed_stage": null,           // present when status is "failed"
  "reason": null                  // present when status is "failed"
}

List jobs

GET/api/v1/jobs

The caller's most-recent jobs (newest first), cursor-paginated. Query params: limit (default 50, 1–100) and before (an ISO-8601 created_at cursor — pass back the previous page's next_before). Backs the SDK's list_jobs / listJobs / ListJobs / ListJobsAsync.

bash

curl "https://api.speechrevolutions.com/api/v1/jobs?limit=50" \
  -H "X-API-Key: $SPEECHREVOLUTIONS_API_KEY"

Response (JobListResponse):

json

{
  "jobs": [
    { "job_id": "…", "created_at": "2026-07-22T18:01:00Z" }
  ],
  "next_before": "2026-07-22T18:01:00Z"   // null on the last page
}

SSE stream

GET/api/v1/jobs/{job_id}/stream

Open a Server-Sent Events stream for a job. Reconnect with the Last-Event-ID header to resume without missing events.

bash

curl -N "https://api.speechrevolutions.com/api/v1/jobs/$JOB_ID/stream" \
  -H "X-API-Key: $SPEECHREVOLUTIONS_API_KEY" \
  -H "Accept: text/event-stream"

Events

The stream emits three event types: progress (repeated), then a terminal completed or failed. The step name depends on how the file was routed: small files skip straight to a chunk:N step; larger files start with preprocess, then either a single chunk:0 (short audio) or multiple chunk:0, chunk:1, … steps (long audio, one per split chunk) followed by aggregation.

stream

event: progress
data: {"completed": 0, "total": 8, "step": "preprocess"}

event: progress
data: {"completed": 3, "total": 8, "step": "chunk:0"}

event: progress
data: {"completed": 8, "total": 8, "step": "aggregation"}

event: completed
data: {"job_id": "…", "download_url": "https://…", "output_type": "json"}

Event	Data
`progress`	`{"completed": <int>, "total": <int>, "step": "<name>"}`
`completed`	Terminal success; data may include a `download_url` and job metadata
`failed`	Terminal failure; `{"step": "<name>", "reason": "<msg>"}`

completed / total → percent

The progress payload carries raw completed and total step counts — not a percentage. A percentage is a client-side convenience: the official SDKs compute percent = completed / total × 100 and surface it as ProgressEvent.percent (which is undefined while total is still unknown). See any SDK page for the live-progress callbacks.

Cancel

POST/api/v1/jobs/cancel

json

{"job_id": "…"}

You can only cancel a job that hasn't already been processed, and only for the portion that hasn't been processed yet. If a job is already substantially complete when your cancellation is received — say most of the audio has been transcribed — we reserve the right to bill for the work already done.

Check failed

POST/api/v1/jobs/check-failed

json

{"job_ids": ["…", "…"]}

Response: {"failed_jobs": [true, false]}