Job reference
What every answer from the jobs API means: at submit, while a job runs and when it ends, with what is charged and what to do next.
Submit a job
POST /v1/jobs with your key as a Bearer token and an Idempotency-Key header of 8 to 128 characters. The body has service_id, input, and optionally max_wait_seconds, 1 to 86400 with a default of 900, and client_reference, up to 256 characters of your own. input is the descriptor for that service; the OpenAPI specification gives every field of every service.
Media goes by link
Every media file in an input is a public https link the renderer fetches with a plain GET and no headers, up to 1 GB each. Keep each link readable until the job has ended: max_wait_seconds plus the render time. To host one file here, POST /v1/assets and PUT the bytes to upload_url, up to 100 MB. Send the file’s sha256 and the same bytes always get the same link. To host a Remotion bundle, send every regular file’s path, byte length and SHA-256 together, PUT every returned upload, and use its serve_url. A bundle can total 1 GB.
Answers at submit
201 is a new job. 200 with the header Idempotency-Replayed: true is the job an earlier request with the same key and body created. 400 invalid_request carries issues, a list of {field, message}; field is a dot path, such as max_wait_seconds or, inside input, clips.0.volume. 400 unsupported_service_or_option means the service is not sold or an option is not offered. 402 insufficient_balance means the balance does not cover the job. 409 no_capacity means no renderer offers the service now or its queue is full. 409 idempotency_conflict means the key was used with a different body. 429 means your organization already has 8 jobs running, where a further submit is refused and not queued (shared_beta_org_active_limit), or 50 queued (shared_beta_org_queue_limit), or passed a request limit (rate_limited, with a Retry-After header).
With another place to render
Treat 409 no_capacity and 429 as go there now. A 400 will be refused again with the same body. Set max_wait_seconds short, so a job no renderer takes ends as expired quickly.
While it runs
A job is queued until a renderer takes it and active while it renders. cancelling means cancellation was asked for while it ran. It ends as succeeded, failed, cancelled or expired. Read it with GET /v1/jobs/{id}, or register a webhook endpoint for job.succeeded, job.failed and job.cancelled. POST /v1/jobs/{id}/cancel cancels it. A job carries four times: created_at, when it was submitted; started_at, when a renderer first took it, null while none has; completed_at, when it reached succeeded, failed, cancelled or expired, null until then; and updated_at, when it last changed. On a finished job updated_at is the moment it ended, the same as completed_at, and nothing changes it afterwards. A job tried again on another renderer keeps its first started_at.
How long a job takes
Measured on 21 November 2026 at light load, from created_at to completed_at. A 6-second timeline export at proxy_480p from two clips took 5.8 seconds at the median over six runs, between 5.4 and 6.2. A 2-second Remotion render of 60 frames took 8.7 seconds at the median, between 8.3 and 9.4. The first export after a quiet spell took 8.0 seconds. A 5-second 1080p export of 150 frames took 6.0 and 6.1 seconds, and 7.4 as the first after a quiet spell. Eight exports submitted together were all finished 26 seconds later. A job goes to the fastest renderer with a free slot, and when none is free it waits a few seconds for one before a slower renderer takes it, so times rise when the service is busy: the same 1080p export took 34.9 seconds on the slowest renderer. POST /v1/jobs/estimate returns the typical render time for a request and how busy the service is.
How long a submit takes
POST /v1/jobs answers once the job exists, in about a second. The first request after about a minute with none takes about 5 seconds, between 4.6 and 6.2 as measured on 21 November 2026. A read of a job, the job list or the balance ends the quiet spell, so one sent when a render is about to be asked for, four seconds or more ahead, makes the submit that follows a one-second one. Preparing an upload does not. Give a submit 15 seconds, and after no answer send it again with the same Idempotency-Key: it returns the job the first send made and creates and charges nothing new. For a few seconds while the service is being updated a submit or a read can answer 502 or 503: send it again, a submit with the same Idempotency-Key. A job that is rendering at that moment keeps rendering and is handed in when it is done.
What is charged, and whether a renderer started
Only a succeeded job is charged, and charged_fee_micros is the charge in millionths of a US dollar. expired with failure_code no_capacity means no renderer took the job within max_wait_seconds: it never started. cancelled from queued never started. failed means a renderer started it. Before a job reads failed, it has already been tried again on another renderer where that could help.
Failure codes
download_failed: a link could not be fetched. invalid_input: the media does not fit the descriptor, for example a required sound stream is missing. runner_failed: the render program failed. upload_failed: the finished file could not be stored. lease_expired and provider_offline: the renderer stopped answering. internal_error: a fault on our side. commit_conflict: the job was finished twice, which is rare. no_capacity, on an expired job: no renderer took it in time. buyer_cancelled, on a cancelled job. failure_message beside the code says what went wrong, for example which link could not be fetched.
The finished file
GET /v1/jobs/{id}/output returns url, a plain public link kept for 3 days. One job produces one file; copy it into your own storage. The job’s output_file gives its extension and content_type.
The result beside the file
A finished job’s result is a JSON object of up to 64 KB with facts about the output: duration_seconds, width and height as measured, where an image has width and height and no length, and whatever the service reports, such as a timeline export’s sound report. It is null until the job completes.
Sending the same job again
A request with the same Idempotency-Key and the same body returns the same job and creates and charges nothing new, so after a submit that got no answer, send it again to learn the job’s ID. The whole request is compared, including max_wait_seconds and client_reference, and a key is remembered as long as its job is. The same key with a different body is refused with 409 idempotency_conflict. For the body to be the same, its links must be the same: name uploads by sha256.
Check a price first
POST /v1/jobs/estimate with the same service_id and input returns a price and the expected start without creating a job. Remotion price_micros does not come from opening the bundle or reading the composition. It is based on frame_range when provided (the inclusive frame count divided by 30 fps), or a 20-second default when frame_range is absent. It is not the final charge: price_is_final is false, and the completed job is charged for its actual output. GET /v1/services/{id}/capacity returns the free slots and the running and queued jobs of a service.