Skip to main content
GET
/
pictoryapis
/
v1
/
jobs
/
{jobid}
Get Video Render Job by ID
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/jobs/{jobid} \
  --header 'Authorization: <authorization>'
{
    "job_id": "265a7c1a-4985-4058-9208-68114f131a2b",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Overview

This endpoint retrieves the current status and results of a video render job using its unique job ID. While rendering is in progress, it returns the job status along with render progress percentage and state. Once the render completes, it returns the full set of output URLs for the rendered video, audio, subtitles, and thumbnail.
A valid API key is required to use this endpoint. Obtain your API key from the API Access page in your Pictory dashboard.

​
API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/jobs/{jobid}

​
Request Parameters

​
Path Parameters

​
jobid
uuid
required
The unique identifier (UUID) of the video render job. This value is the jobId returned by the Render from Preview, Render Video, Render Storyboard Video, or Render Project endpoints.Example: "265a7c1a-4985-4058-9208-68114f131a2b"

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

​
Response

​
In-Progress Response

Returned while the video is being rendered. The response includes progress information once rendering has started:
​
job_id
string
The unique identifier of the render job
​
success
boolean
true while the job is processing
​
data
object
​
status
string
"in-progress" — the video is still being rendered
​
renderProgress
number
Rendering progress as a percentage (0–100). Present only after rendering has started.
​
renderProgressMessage
string
Descriptive progress message (e.g., "Generating video"). Present only after rendering has started.
​
renderState
string
Current render state (e.g., "RUNNING"). Present only after rendering has started.

​
Failed Response

Returned when the render job has failed:
​
job_id
string
The unique identifier of the render job
​
success
boolean
false when the job has failed
​
data
object
​
status
string
"failed" — the video render has failed
​
error_code
string
Error code identifying the failure type
​
error_message
string
Descriptive message explaining the cause of the failure

​
Completed Response

Returned when the render has finished successfully. The response contains all output URLs:
​
job_id
string
The unique identifier of the render job
​
success
boolean
true when the job has completed successfully
​
data
object
Contains the complete render output.
​
status
string
"completed" — the video has been rendered successfully
​
progress
number
100 — rendering is complete
​
videoURL
string
Direct download URL for the rendered video file (MP4)
​
videoShareURL
string
Shareable URL for the rendered video
​
videoEmbedURL
string
Embeddable URL for the rendered video, suitable for iframe integration
​
audioURL
string
Direct download URL for the audio track (MP3)
​
thumbnail
string
URL for the video thumbnail image (JPG)
​
srtFile
string
URL for the SRT subtitle file
​
txtFile
string
URL for the plain text transcript file
​
vttFile
string
URL for the WebVTT subtitle file
​
videoDuration
number
Total duration of the rendered video in seconds
​
encodingDuration
number
Time taken to encode and render the video in seconds

​
Response Examples

{
    "job_id": "265a7c1a-4985-4058-9208-68114f131a2b",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Completed Response Fields

FieldDescription
videoURLDirect download link for the rendered MP4 video file
videoShareURLShareable link to view the video on Pictory
videoEmbedURLEmbeddable URL suitable for iframe integration
audioURLDirect download link for the extracted MP3 audio track
thumbnailURL for the auto-generated video thumbnail (JPG)
srtFileSRT subtitle file compatible with standard video players
txtFilePlain text transcript file
vttFileWebVTT subtitle file for web-based video players
videoDurationTotal video length in seconds
encodingDurationTotal rendering time in seconds

​
Code Examples

Replace YOUR_API_KEY with your actual API key and use the jobId returned from any render endpoint.
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/jobs/265a7c1a-4985-4058-9208-68114f131a2b' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

​
Render Progress Stages

The render job progresses through the following stages:
StagestatusrenderStateDescription
Queuedin-progress—Job is queued; pre-processing has not started
Processingin-progressRUNNINGPre-render processing (scene composition, audio mixing)
Renderingin-progressRUNNINGVideo frame rendering is in progress
Completedcompleted—Video is ready for download
Failedfailed—Render has failed; check error_code and error_message for details

​
Polling Best Practices

Use a polling interval of 10–30 seconds when checking job status. Polling too frequently may result in rate limiting.
  1. Use webhooks when possible. Configure a webhook URL in the original render request to receive automatic notification when the job completes, rather than polling.
  2. Monitor renderProgress. Use the renderProgress field to display progress to users. This field provides a percentage value from 0 to 100.
  3. Implement timeouts. Set a maximum wait time based on expected video length. Longer videos require more rendering time.
  4. Cache results. Once a render job completes, store the output URLs locally. Completed job data may be cleaned after a retention period.
  5. Handle failures gracefully. Inspect error_code and error_message in failed responses to determine whether the issue is recoverable (for example, an invalid voice name can be corrected and the request resubmitted).