> For the complete documentation index, see [llms.txt](https://developer.topazlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.topazlabs.com/reference/video/get-request-status/get-video-request-status.md).

# Get Video Request Status

Get status of the request.

If processing is complete, the response will include a signed URL to access the enhanced video.

Make sure to download and save the video within the TTL provided in the response (7 days by default). The signed URL is generated once and then reused: calling this endpoint again returns the same URL and the same expiry rather than issuing a fresh one. We retain your data for only a limited number of days, after which the video is permanently deleted from our system.

### Response body

| **Property**       | **Type** | **Description**                                                               |
| ------------------ | -------- | ----------------------------------------------------------------------------- |
| **status**         | String   | Current processing status                                                     |
| **message**        | String   | Human-readable status message                                                 |
| **errorCode**      | String   | Failure code from the processing pipeline, present only when status is failed |
| **progress**       | Number   | Total request progress (percentage)                                           |
| **estimates**      | Object   | Refer to **RequestEstimates**                                                 |
| **uploadId**       | String   | Present while the request is awaiting source upload                           |
| **urls**           | Array    | Outstanding upload URLs, present while the request is awaiting source upload  |
| **outputSize**     | String   | Size of output video                                                          |
| **averageFps**     | Number   | Average FPS of processing nodes                                               |
| **combinedFps**    | Number   | Combined FPS of all nodes                                                     |
| **processingJobs** | Array    | Refer to **VideoProcessingStatIntermediate** below                            |
| **download**       | Object   | Refer to **EnhancedDownloadSignedUrlResponse** below                          |
| **comparisonTool** | String   | URL to a before/after comparison view, present only for free renders          |

`outputSize`, `averageFps`, `combinedFps` and `processingJobs` are reported for chunked enhancement requests. They are absent for requests handled end-to-end by the inference backend.

***

**RequestEstimates**

`cost` and `time` are arrays with two integers each, representing lower and upper bounds of the estimate.

| **Property** | **Type** | **Description**         |
| ------------ | -------- | ----------------------- |
| **cost**     | Array    | Cost range (in credits) |
| **time**     | Array    | Time range (in seconds) |

***

**VideoProcessingStatIntermediate**

| **Property**                    | **Type** | **Description**                             |
| ------------------------------- | -------- | ------------------------------------------- |
| **chunkId**                     | UUID     | Unique chunk identifier                     |
| **chunkIndex**                  | Integer  | Index of the chunk                          |
| **taskIndex**                   | Integer  | Task index for chunk processing             |
| **status**                      | String   | Status (queued, processing, complete, etc.) |
| **progress**                    | Number   | Processing progress (percentage)            |
| **averageFps**                  | Number   | Processing speed of the node                |
| **averageGpuUtilization**       | Number   | GPU utilization in percentage               |
| **averageGpuMemoryUtilization** | Number   | GPU memory usage percentage                 |

***

**EnhancedDownloadSignedUrlResponse**

| **Property**  | **Type** | **Description**                           |
| ------------- | -------- | ----------------------------------------- |
| **url**       | String   | Signed download URL for the enhanced file |
| **expiresIn** | Integer  | TTL in milliseconds                       |
| **expiresAt** | Integer  | Time in milliseconds since UTC epoch      |

```json
{"openapi":"3.0.3","info":{"title":"Video API","version":"1.0.0"},"tags":[{"name":"Get Request Status","description":"This section allows you to get the status of a request\n"}],"servers":[{"url":"https://api.topazlabs.com","description":"Production API base URL"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"StatusResponse":{"type":"object","properties":{"status":{"type":"string","enum":["requested","accepted","initializing","preprocessing","processing","postprocessing","complete","canceling","canceled","failed"]},"progress":{"type":"number","description":"Total progress of the request in percentage"},"estimates":{"$ref":"#/components/schemas/RequestEstimates"},"outputSize":{"type":"string"},"averageFps":{"type":"number","description":"Average processing speed of each node"},"combinedFps":{"type":"number","description":"Combined processing speed of all nodes"},"message":{"type":"string"},"errorCode":{"type":"string","description":"Present only when `status` is `failed`. Originates from the processing pipeline.\n\nKnown values include:\n- INSUFFICIENT_CREDITS\n- CREDIT_DIFFERENCE\n- INVALID_INPUT\n- FORBIDDEN\n- UNAUTHORIZED\n- TIMEOUT_UPLOAD_SOURCE\n- TIMEOUT_QUEUE\n- TIMEOUT_PROCESSING\n- PROCESSING_FAILURE\n- SERVER_MAINTENANCE\n- SERVER_ERROR\n- HARDWARE_FAILURE\n- UNKNOWN\n"},"processingJobs":{"$ref":"#/components/schemas/ProcessingStatIntermediate"},"uploadId":{"type":"string","description":"Present only while the request is still awaiting the source upload"},"urls":{"type":"array","description":"Outstanding upload URLs, present only while the request is still awaiting the source upload","items":{"type":"string"}},"comparisonTool":{"type":"string","description":"URL to a before/after comparison view. Present only for free renders."},"download":{"$ref":"#/components/schemas/EnhancedDownloadSignedUrlResponse"}}},"RequestEstimates":{"type":"object","description":"Lower and upper bound estimates","properties":{"cost":{"type":"array","description":"In credits","items":{"type":"integer"}},"time":{"type":"array","description":"In seconds, assuming an empty queue, starting from the time the source video has been received","items":{"type":"integer"}}}},"ProcessingStatIntermediate":{"type":"array","description":"Processing state for each chunk","items":{"type":"object","properties":{"chunkId":{"type":"string","format":"uuid"},"chunkIndex":{"type":"integer","description":"Index of the chunk starting from 0"},"taskIndex":{"type":"integer","description":"Index of a chunk's enhancement task starting from 0"},"status":{"type":"string","enum":["queued","processing","complete","canceled","failed"]},"progress":{"type":"number","description":"In percentage"},"averageFps":{"type":"number","description":"Processing speed of the node"},"averageGpuUtilization":{"type":"number","description":"In percentage"},"averageGpuMemoryUtilization":{"type":"number","description":"In percentage"}}}},"EnhancedDownloadSignedUrlResponse":{"type":"object","description":"Signed download URL to the enhanced video file.\n\nThe URL is generated once and then reused for the lifetime of the request — subsequent calls return the same `url`, `expiresIn` and `expiresAt` rather than a freshly signed URL.\n","properties":{"url":{"type":"string"},"expiresIn":{"type":"integer","description":"TTL in milliseconds. Defaults to 7 days."},"expiresAt":{"type":"integer","description":"Time in milliseconds since UTC epoch"}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]}}}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]}}}}}},"NotFound":{"description":"Enhancement request with the provided ID not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]}}}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]}}}}}}}},"paths":{"/video/{requestId}/status":{"get":{"tags":["Get Request Status"],"summary":"Get Video Request Status","operationId":"GetVideoRequestStatus","description":"Get status of the request.\n\nIf processing is complete, the response will include a signed URL to access the enhanced video.\n\nMake sure to download and save the video within the TTL provided in the response (7 days by default). The signed URL is generated once and then reused: calling this endpoint again returns the same URL and the same expiry rather than issuing a fresh one. We retain your data for only a limited number of days, after which the video is permanently deleted from our system.\n\n## Response body\n\n| **Property**         | **Type**  | **Description**                                   |\n|---------------------|----------|-----------------------------------------------------|\n| **status**           | String   | Current processing status                          |\n| **message**          | String   | Human-readable status message                      |\n| **errorCode**        | String   | Failure code from the processing pipeline, present only when status is failed |\n| **progress**         | Number   | Total request progress (percentage)                |\n| **estimates**        | Object   | Refer to **RequestEstimates**                      |\n| **uploadId**         | String   | Present while the request is awaiting source upload |\n| **urls**             | Array    | Outstanding upload URLs, present while the request is awaiting source upload |\n| **outputSize**       | String   | Size of output video                               |\n| **averageFps**       | Number   | Average FPS of processing nodes                    |\n| **combinedFps**      | Number   | Combined FPS of all nodes                          |\n| **processingJobs**   | Array    | Refer to **VideoProcessingStatIntermediate** below   |\n| **download**         | Object   | Refer to **EnhancedDownloadSignedUrlResponse** below |\n| **comparisonTool**   | String   | URL to a before/after comparison view, present only for free renders |\n\n`outputSize`, `averageFps`, `combinedFps` and `processingJobs` are reported for chunked enhancement requests. They are absent for requests handled end-to-end by the inference backend.\n\n---\n\n#### RequestEstimates\n\n`cost` and `time` are arrays with two integers each, representing lower and upper bounds of the estimate.\n\n| **Property**  | **Type**  | **Description**                                    |\n|---------------|----------|-----------------------------------------------------|\n| **cost**      | Array    | Cost range (in credits)                             |\n| **time**      | Array    | Time range (in seconds)                             |\n\n---\n\n#### VideoProcessingStatIntermediate\n\n| **Property**         | **Type**  | **Description**                                   |\n|---------------------|----------|-----------------------------------------------------|\n| **chunkId**          | UUID     | Unique chunk identifier                            |\n| **chunkIndex**       | Integer  | Index of the chunk                                 |\n| **taskIndex**        | Integer  | Task index for chunk processing                    |\n| **status**           | String   | Status (queued, processing, complete, etc.)        |\n| **progress**         | Number   | Processing progress (percentage)                   |\n| **averageFps**       | Number   | Processing speed of the node                       |\n| **averageGpuUtilization** | Number | GPU utilization in percentage                    |\n| **averageGpuMemoryUtilization** | Number | GPU memory usage percentage                |\n\n---\n\n#### EnhancedDownloadSignedUrlResponse\n\n| **Property**   | **Type**  | **Description**                 |\n|----------------|-----------|---------------------------------|\n| **url**        | String    | Signed download URL for the enhanced file |\n| **expiresIn**  | Integer   | TTL in milliseconds                  |\n| **expiresAt**  | Integer   | Time in milliseconds since UTC epoch |\n","parameters":[{"in":"path","name":"requestId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.topazlabs.com/reference/video/get-request-status/get-video-request-status.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.