202 with the Job and Location: /v3/jobs/{job_id}. (createProjectCopies starts several, so it answers with a list and no
Location; each job has links.self.)
Status
A job moves one way and never back:
Because status never moves back, resuming a failed run makes a new job, and a failed job needs a new
Idempotency-Key to start again.
Waiting
wait_seconds, 20 at most, holds the request until the job changes or ends, or until the wait is over. Loop on it until a terminal status, and do not ask faster than the Retry-After header of the answer, which holds the poll hint of the job’s type.
With If-None-Match set to the ETag of the last answer, an unchanged job answers 304. A terminal job ignores it and always answers 200, because a refund or fresh links can change the body after the job ended.
By default a key may hold 10 waits at once, and a payer 50; a trial allows fewer. These counts are approximate, like the request limits. Beyond them a wait answers 429 too_many_waiters: wait Retry-After, or ask again without wait_seconds.
How long a job takes
estimated_finish_at estimates the end from the queue position and the type’s typical duration, and turns null once the job runs past that estimate. An on-screen job that has started shows its run’s own estimate instead. queue_position says where the job stands in its queue (1 is next). Only a lip-sync or on-screen job that waits in a queue has one, and a localization run shows its running stage’s; otherwise it is null. x-rask-operation.typical_duration_seconds in the contract holds a p50 and a p95 per
starting operation. They are typical durations, not guarantees or deadlines.
For long jobs, keep the id and check back later rather than hold a wait for hours. The wait of an SDK gives up after 4 hours unless you pass a longer timeout, and the job keeps running. A
localization run can take longer than that (p95 4 h 15 min), and a file_restore often does (p50 4 h, p95 12 h), so give their waits a longer timeout, or save the id and check back. overdue turns true when a job runs well past its type’s typical duration: Rask is alerted, and the job may still finish. Keep waiting or check back later, and do not start the same work again.
What a job holds
Which work has a job
Jobs exist for work started through v3, and for automatic follow-up work on projects created through v3. Work started in the web app or API v2 has no job: readprocessing_state on the project, or the lip-sync and
on-screen state, where such a result shows with job_id: null.
A finished job can be read and listed for 90 days after it ends. After that it answers 404 job_not_found.
Canceling
cancelJob works on two kinds of job: amedia_import that has not ended, and an onscreen job that is queued and not charging (its minutes come back). Everything else answers 409 job_not_cancelable, including a
localization run and an onscreen job that is one of its stages. A job that has already ended answers 409 job_already_finished.
Deleting a project ends its active jobs as canceled, and discards their work: only on-screen runs are refunded. A project with active spending work answers 409 project_busy unless you send force=true.
Listing
listJobs lists jobs newest first and filters byproject_id, media_id, type, status, channel and created_after; type and status take comma-separated lists. A job another key started is read and listed only with the scope that reads what it works on: see Scopes. A project’s own active_jobs lists its jobs that have not ended.