Submissions

Get submission

Returns the current status of a clipping submission. Poll this endpoint until status is completed or failed.

We recommend polling every 5–10 seconds. When status is queued, use queue_position and estimated_time to give feedback to your users.

A submission can sit at downloading because the SOURCE is not fully published yet — a scheduled premiere, a livestream still on air, or a recording the platform is still processing. In that case waiting_reason is set (and waiting_until carries the announced start time, when the platform provides one). This is not an error and the submission is not stuck: it resumes on its own once the source becomes available. Surface it to your users instead of a generic "downloading", and offer them the option to cancel — DELETE /v1/clips/{videoId}/submissions/{submissionId} refunds the credits while waiting_reason is set.

get/clips/{videoId}/submissions/{submissionId}

Request

  • Base URL: https://api.cut.pro/api/v1
  • URL: https://api.cut.pro/api/v1/clips/{videoId}/submissions/{submissionId}
  • Auth: API key in header X-Api-Key

Path parameters

videoIdstring required
submissionIdstring required

Response

Response for status 200

idstring required

Unique submission ID

video_idstring required

ID of the source video

status'queued' | 'downloading' | 'transcribing' | 'video_analysis' | 'analyzing' | 'finalizing' | 'completed' | 'failed' required
error_code'DOWNLOAD_FAILED' | 'DOWNLOAD_ACCESS_DENIED' | 'DOWNLOAD_MEMBERS_ONLY' | 'DOWNLOAD_PRIVATE_VIDEO' | 'DOWNLOAD_GEO_RESTRICTED' | 'DOWNLOAD_TIMEOUT' | 'DOWNLOAD_NETWORK' | 'DOWNLOAD_NO_AUDIO' | 'DOWNLOAD_NOT_AVAILABLE' | 'DOWNLOAD_REMOVED_BY_UPLOADER' | 'DOWNLOAD_PREMIERE_NOT_STARTED' | 'DOWNLOAD_LIVE_IN_PROGRESS' | 'TRANSCRIBE_FAILED' | 'VIDEO_ANALYSIS_FAILED' | 'ANALYZE_FAILED' | 'GENERATE_FAILED' | 'EMPTY_TRANSCRIPT' | 'UPLOAD_CORRUPTED' | 'UNKNOWN' nullable required
clips_countnumber required

Number of AI-generated clips available; only meaningful when status is completed

queue_positionnumber nullable required

Position in the processing queue; null once processing has started

estimated_timenumber nullable required

Estimated seconds until completion; null once processing has started

waiting_reason'SOURCE_PREMIERE_SCHEDULED' | 'SOURCE_LIVE_IN_PROGRESS' | 'SOURCE_VOD_PROCESSING' nullable required

Why the submission is waiting on its source: SOURCE_PREMIERE_SCHEDULED (scheduled premiere that has not aired), SOURCE_LIVE_IN_PROGRESS (livestream still on air), SOURCE_VOD_PROCESSING (broadcast ended, platform still publishing the recording).

waiting_untilstring nullable required

ISO 8601 timestamp the platform announced for the premiere, when known; null if there is no announced time

created_atstring required

ISO 8601 timestamp of when this submission was created

completed_atstring nullable required

ISO 8601 timestamp of when this submission finished, or null if still running

Changes

No recorded changes to this operation across all 1 revision of this API.