film status

film status JOB_ID [--settled] [--json]

Reads one job back through the Film at FILM_URL. Film asks the renderer that started the job, so the answer is the renderer's, not a cached copy. Changes nothing.

• Without --settled: what the renderer says now.
• With --settled: Film holds the read until the job is completed or failed, released when the renderer's callback arrives and Film reads back a terminal state. If that completion read fails, the held request ends with the operation's cause instead of remaining open. Nothing re-reads on a timer; a renderer that never delivers its callback leaves the read open, and a plain read still answers its state.

job_id: <id>
pipeline: <pipeline>
status: completed
url: <video url>
error: -
completed_at: <RFC 3339 time>

With --json the same job as JSON; fields with no value are left out.

Refusals

Exit 1: a job whose status is failed, after it is printed; film refused (404): this deployment did not start job `<id>`; film refused (409): job `<id>` was started on `<pipeline>`, which is no longer configured here; film refused (410): job `<id>` was dropped from this deployment's record while held; film refused (502): reading callback completion for <pipeline> job `<id>` failed: <cause>; film at <url> — <cause> when the service cannot be reached; and the configuration refusals. A missing job id exits 2.

A completion-read error does not mean the render failed. Film retains the renderer's last observed state. A later successful provider read clears the read diagnostic; an older processing response cannot replace a terminal state already observed.

Hedra, KIE and WaveSpeed status HTTP refusals, body-read failures and invalid JSON are observation errors, not terminal render failures. Their diagnostics name the provider, job, operation, observed HTTP status and full response or parsing cause. A completed response with no usable output URL also refuses the read. A failed render is reported separately from a status-read error. Status waits log their start and outcome.

KIE also reports request refusals inside an HTTP-success JSON response. Film checks its code before interpreting the job document and reports the job, provider code and msg as an observation error; the last recorded job state is preserved. For an actual fail job, the terminal error retains failCode and failMsg, including whether the provider omitted either value.