Media Service

Batch fetch videos with clip configurations

post

https://api.typeform.com/media/videos/list

Retrieves multiple videos with optional per-video clip time configurations for instant clipping.

Features:

Fetch multiple videos in a single request
Apply per-video clip times (start_time, end_time) for instant clipping
Get signed Mux playback tokens for secure video access
Support for millisecond or second time units

Authentication:

Requires Authorization header with bearer token OR
Respondent token in request body for form respondent access

Instant Clipping: Videos can be clipped on-the-fly without creating new files. The returned playback URLs will only stream the specified time range. Tokens include clip parameters as JWT claims.

Request

Request Body

clip_time_unit

string

Valid values:sms

Default:s

Time unit for start_time and end_time values:

"s": seconds (default)
"ms": milliseconds (will be converted to seconds)

form_id

string

Unique ID for the form

respondent_token

string

Optional respondent authentication token (alternative to Authorization header). Used when accessing videos as a form respondent.

status

string

Valid values:readyprocessingupload_pending

Optional filter to only return videos with specific transcode status

videos

array of object

List of videos to fetch with optional clip configurations

end_time

number

Optional end time for instant clipping. Unit depends on clip_time_unit parameter.

string, required

Video reference ID

start_time

number

Optional start time for instant clipping. Unit depends on clip_time_unit parameter.

Responses

Status

200 Videos retrieved successfully

Schema

Example

[
  {
    "duration_seconds": 20,
    "gif_preview_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "gif_preview_url": "https://image.mux.com/playback123/animated.webp?token=eyJhbGc...",
    "id": "video-ref-abc123",
    "playback_id": "playback123",
    "playback_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleTEyMyJ9...",
    "playback_url": "https://stream.mux.com/playback123.m3u8?token=eyJhbGc...",
    "source_href": "https://api.typeform.com/media/videos/source-ref-id",
    "storyboard_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "storyboard_url": "https://image.mux.com/playback123/storyboard.json?token=eyJhbGc...",
    "thumbnail_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "thumbnail_url": "https://image.mux.com/playback123/thumbnail.webp?token=eyJhbGc...",
    "transcode_status": "ready"
  }
]

Status

400 Bad request - invalid input or clip_time_unit

Schema

code

string

Error code identifying the type of error

details

object

Additional error details specific to the error type

message

string

Human-readable error message

status

string

Valid values:error

Status

401 Unauthorized - invalid or missing authentication

Schema

code

string

Error code identifying the type of error

details

object

Additional error details specific to the error type

message

string

Human-readable error message

status

string

Valid values:error

Status

403 Forbidden - access denied to private video

Schema

code

string

Error code identifying the type of error

details

object

Additional error details specific to the error type

message

string

Human-readable error message

status

string

Valid values:error

Status

404 Videos not found

Schema

code

string

Error code identifying the type of error

details

object

Additional error details specific to the error type

message

string

Human-readable error message

status

string

Valid values:error