---
title: "Get a video background removal job"
method: GET
path: "/v1/video-background-removal/{job_id}"
tags: ["Video Background Removal"]
---

# Get a video background removal job

`GET /v1/video-background-removal/{job_id}`

Retrieve the current state of a video background removal job by its `job_id`.

The response uses the shared job envelope, whose `status` is one of:

- **`PROCESSING`** — still rendering; the result is empty
- **`COMPLETED`** — done; the result holds the rendered file(s): one WebM with an alpha channel for `vp9`, or the RGB video and the alpha matte (two files) for `h264`
- **`FAILED`** — the job was accepted but rendering failed; the error holds a failure code

Poll this endpoint until the status is `COMPLETED` or `FAILED`. An unknown `job_id` returns `404 Not Found`.

## Path parameters

- `job_id` string, uuid, required — Identifier of the video background removal job, returned when the job was submitted.

## Headers

- `X-Veed-Store-IO` '0' | '1'
- `X-Veed-Media-Expiration-Seconds` integer

## Response `200`

OK

- ResourceVideoBackgroundRemovalJob
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` VideoBackgroundRemovalJob, required
    - `credits_charged` integer — Credits charged for the job. Present once the job is COMPLETED and the final charge is known.
    - `credits_estimated` integer — Credits quoted before the job ran. Present only on the response that created the job. This is an estimate, not the price: the charged amount can be higher or lower.
    - `error` JobErrorVideoBackgroundRemovalErrorCode
      - `code` 'input_validation' | 'content_moderation' | 'invalid_file' | 'audio_too_long' | 'transload_failed' | 'generation_failed' | 'timeout', required — Stable, machine-readable failure code for this job type.
      - `details` JobErrorDetail[], nullable — Optional structured failure details.
        - `field` string — Dotted path to the offending input, when applicable.
        - `message` string, required — Human-readable explanation of this detail.
        - `type` string, required — The category of this detail entry.
      - `message` string, required — Human-readable failure message.
    - `job_id` string, uuid, required — Stable identifier of the job and of the resource it produces.
    - `result` VideoBackgroundRemovalFiles
      - `files` File[], nullable, required — Rendered background-removed file(s): one webm with alpha for vp9; the RGB video and the alpha matte (two files) for h264.
        - `content_type` string — The mime type of the file.
        - `file_name` string — The name of the file.
        - `file_size` integer — The size of the file in bytes.
        - `url` string, required — The URL where the file can be downloaded from.
    - `status` 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED', required — Current lifecycle state of the job.

## Other responses

- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity
- `429` — Rate limit exceeded
- `500` — Internal Server Error

## Changes

- **2026-09-30** `2cd55951003c` — 11 warning, 2 info
  - for the `header` request parameter `X-Veed-Media-Expiration-Seconds`, the max was set to `2592000.00`
  - added the new `insufficient_credits` enum value to the `error/details/items/reason` response property for the response status `401`
  - added the new `insufficient_credits` enum value to the `error/details/items/reason` response property for the response status `404`
  - added the new `insufficient_credits` enum value to the `error/details/items/reason` response property for the response status `422`
  - …9 more
- **2026-09-07** `c4f034a2cec6` — 10 warning
  - added the new `api_key_workspace_unavailable` enum value to the `error/details/items/reason` response property for the response status `401`
  - added the new `api_key_workspace_unavailable` enum value to the `error/details/items/reason` response property for the response status `404`
  - added the new `api_key_workspace_unavailable` enum value to the `error/details/items/reason` response property for the response status `422`
  - added the new `api_key_workspace_unavailable` enum value to the `error/details/items/reason` response property for the response status `429`
  - …6 more

[Change history](https://skmtc.dev/veed/apis/veed-api/changes/v1/video-background-removal/:job_id/get.md)

---

[API](https://skmtc.dev/veed/apis/veed-api.md) · [All operations](https://skmtc.dev/veed/apis/veed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/veed/apis/veed-api/revisions/2cd55951003c?raw)