# List available videos

Returns a paginated list of available videos based on filtering specifications.
Use this endpoint to poll whether requested videos have been prepared and are
available for downloading. Each element specifies the video source, time range,
and provides a downloadable link (which may be valid temporarily).

Endpoint: GET /video-hero/v1/videos
Version: 1.11.0
Security: apiKey

## Query parameters:

  - `customerId` (string, required)
    Unique identifier for the customer
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `truckId` (string)
    Filter by truck identifier
    Example: "truck-5201"

  - `cameraId` (string)
    Filter by camera identifier or placement name
    Example: "front"

  - `requestId` (string)
    Filter by a specific video request ID
    Example: "req-abc123-def456"

  - `startTime` (string)
    Filter videos starting from this ISO 8601 timestamp
    Example: "2026-02-04T08:30:00Z"

  - `endTime` (string)
    Filter videos ending before this ISO 8601 timestamp
    Example: "2026-02-04T08:35:00Z"

  - `page` (integer)
    Page number for pagination
    Example: 1

  - `pageSize` (integer)
    Number of results per page
    Example: 20

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Whether the request was successful
    Example: true

  - `data` (object, required)

  - `data.videos` (array)
    List of available videos

  - `data.videos.id` (string, required)
    Unique identifier for the video
    Example: "vid-001"

  - `data.videos.requestId` (string)
    The request ID that initiated this video preparation
    Example: "req-abc123-def456"

  - `data.videos.customerId` (string, required)
    Customer identifier
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `data.videos.truckId` (string, required)
    Truck identifier
    Example: "truck-5201"

  - `data.videos.cameraId` (string, required)
    Camera identifier
    Example: "front"

  - `data.videos.startTime` (string, required)
    Start time of the video clip
    Example: "2026-02-04T08:30:00Z"

  - `data.videos.endTime` (string, required)
    End time of the video clip
    Example: "2026-02-04T08:35:00Z"

  - `data.videos.status` (string, required)
    Current status of the video
    Enum: "processing", "ready", "expired", "failed"

  - `data.videos.downloadUrl` (string)
    Temporarily valid URL for downloading the video file.
Only present when status is "ready". Ample time is provided for downloading.
    Example: "https://storage.yourcompany.com/videos/vid-001.mp4?token=abc123&expires=1738800000"

  - `data.videos.expiresAt` (string)
    Timestamp when the download URL expires
    Example: "2026-02-05T08:30:00Z"

  - `data.pagination` (object)

  - `data.pagination.page` (integer)
    Current page number
    Example: 1

  - `data.pagination.pageSize` (integer)
    Number of items per page
    Example: 20

  - `data.pagination.totalItems` (integer)
    Total number of items across all pages
    Example: 48

  - `data.pagination.totalPages` (integer)
    Total number of pages
    Example: 3

## Response 400 fields (application/json):

  - `success` (boolean, required)
    Always false for errors

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "INVALID_PAYLOAD", "UNAUTHORIZED", "INTERNAL_ERROR", "NOT_FOUND"

  - `error.message` (string, required)
    Human-readable error message
    Example: "Missing required field: truckId"

  - `error.details` (object)
    Additional error details (optional)

## Response 401 fields (application/json):

  - `success` (boolean, required)
    Always false for errors

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "INVALID_PAYLOAD", "UNAUTHORIZED", "INTERNAL_ERROR", "NOT_FOUND"

  - `error.message` (string, required)
    Human-readable error message
    Example: "Missing required field: truckId"

  - `error.details` (object)
    Additional error details (optional)

## Response 500 fields (application/json):

  - `success` (boolean, required)
    Always false for errors

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "INVALID_PAYLOAD", "UNAUTHORIZED", "INTERNAL_ERROR", "NOT_FOUND"

  - `error.message` (string, required)
    Human-readable error message
    Example: "Missing required field: truckId"

  - `error.details` (object)
    Additional error details (optional)