Skip to main content
GET
/
pictoryapis
/
v1
/
jobs
/
{jobid}
Get Transcription Job by ID
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/jobs/{jobid} \
  --header 'Authorization: <authorization>'
{
    "job_id": "cbbc5305-3c1c-46f0-bdde-468e5ecd763f",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Overview

This endpoint retrieves the current status and results of a transcription job using its unique job ID. While processing is in progress, it returns the current job status. Once the job completes, it returns the full transcript data including word-level timing, speaker identification, and subtitle formats (SRT, VTT).
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 transcription job. This value is the jobId returned by the Video Transcription endpoint.Example: "cbbc5305-3c1c-46f0-bdde-468e5ecd763f"

​
Headers

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

​
Response

​
In-Progress Response

Returned while the transcription is still being processed:
​
job_id
string
The unique identifier of the transcription job
​
success
boolean
true while the job is processing
​
data
object
​
status
string
"in-progress" — transcription is still being processed

​
Completed Response

Returned when the transcription has finished successfully. The response contains the full transcript data:
​
success
boolean
true when the job has completed successfully
​
job_id
string
The unique identifier of the transcription job
​
data
object
Contains the complete transcription results.

​
Response Examples

{
    "job_id": "cbbc5305-3c1c-46f0-bdde-468e5ecd763f",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Code Examples

Replace YOUR_API_KEY with your actual API key and use the jobId returned from the Video Transcription endpoint.
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/jobs/cbbc5305-3c1c-46f0-bdde-468e5ecd763f' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

​
Understanding the Transcript Response

The completed transcription response includes several output formats:
FieldDescription
transcriptStructured array of segments with word-level timing, speaker IDs, and pause markers. Suitable for building custom subtitle renderers or transcript editors.
txtFull transcript as plain text. Suitable for search indexing, summarization, or display.
srtTranscript in SRT subtitle format. Can be saved directly as a .srt file for video players.
vttTranscript in WebVTT format. Can be saved as a .vtt file for web-based video players.
mediaInfoSource media metadata including duration, dimensions, and aspect ratio.

​
Pause Markers

The transcript array includes pause markers alongside spoken words. These entries are identified by the following characteristics:
  • is_pause is set to true
  • The word field contains an empty string
  • pause_size indicates the duration category (e.g., "small")
Pause markers are useful for understanding speech pacing and can be leveraged when building transcript-based editing workflows.

​
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 transcription request to receive automatic notification when the job completes, rather than polling.
  2. Implement timeouts. Set a maximum wait time based on the expected file duration. Longer files require more processing time.
  3. Handle all states. Verify both the in-progress status and the presence of transcript data in the response to determine completion.
  4. Cache results. Once a transcription job completes, store the results locally. Completed job data may be cleaned after a retention period.