---
title: "Get Video Details"
method: GET
path: "/v2/videos/{video_id}"
tags: ["Video Emotion API"]
---

# Get Video Details

`GET /v2/videos/{video_id}`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v2/videos/{video_id}`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.imentiv.ai/oauth/authorize`
    - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `media.read`

Retrieve all details for a specific video directly from the database.

Returns a complete standardized response with all possible fields.
Fields that don't exist in the database are returned as null.

**Access Control:**
- Authenticated users can access their own videos
- Admins can access all videos
- Sample videos and shared videos are publicly accessible

## Path parameters

- `video_id` string, required: The unique ID of the video.

## Response `200`

Successful Response

- VideoDetailResponseV2: Complete V2 response model for video details with all possible fields. Returns null for fields that don't exist in the database, except diarization/text_emotion/transcription, which default to true when absent (enabled-by-default speech stages, matching the upload contract). Fields are ordered alphabetically.
  - `languages` string[]: Detected languages in stored dominant-first order; empty when unavailable. Short stretches may have line language marks without appearing in this list. This is an output summary, independent of the expected_languages input hint.
  - `annotated_video` string, nullable: Annotated video URL
  - `annotated_video_mp4` string, nullable: Annotated video MP4 URL
  - `annotated_video_percentage` string, nullable: Annotated video progress
  - `annotated_video_status` string, nullable: Annotated video status
  - `audio_csv_url` string, nullable: Audio-specific CSV analysis URL
  - `audio_id` string, nullable: Associated audio analysis ID
  - `audio_transcription` string, nullable: Audio transcription text
  - `auto_translation` AutoTranslation: The automatic main-language translation of a mixed-language audio, as the last completed run left it.
    - `language` string, required: The audio's main language the lines were to be translated into.
    - `status` 'requested' | 'skipped', required: `requested` or `skipped`.
    - `reason` 'insufficient_credits' | 'unavailable', nullable: Why a `skipped` one was skipped. Present only for the owner, and only when `status` is `skipped`.
  - `bulk_upload_id` string, nullable: Bulk upload batch ID
  - `check_audio` boolean, nullable: Whether audio should be checked
  - `completed_at` string, nullable: Completion timestamp
  - `compressed_frames_data_url` string, nullable: Deprecated: always null. The frames archive is an internal format; read frames through the frames routes.
  - `compressed_frames_last_updated_at` string, nullable: Compressed frames last update timestamp
  - `compressed_frames_schema_version` string, nullable: Schema version for compressed frames
  - `created_at` string, nullable: Creation timestamp
  - `updated_at` string, nullable: ISO-8601 UTC timestamp of the last change to this video. Compare it for inequality with the value you hold to tell whether your copy is stale; it carries no ordering guarantee. It covers this video's own fields only, not data derived from other records such as frames or analytics.
  - `csv_analysis_url` string, nullable: CSV analysis file URL
  - `csv_status` string, nullable: CSV generation status
  - `description` string, nullable: Video description
  - `dropbox_url` string, nullable: Dropbox URL if applicable
  - `duration` number, nullable: Video duration in seconds
  - `emotions_list` string[], nullable: List of emotion labels
  - `end_millis` number, nullable: End time in milliseconds
  - `expected_languages` string[]: The languages you said the video's audio track may contain, as sent on upload or reprocess (Whisper codes, main language included). This is the INPUT you gave, not the languages detected in the speech. `[]` when none was given.
  - `face_deletion_status` string, nullable: Face deletion status
  - `face_duplicate_count` integer, nullable: Count of duplicate faces detected
  - `face_emotions` object, nullable: Face emotions per face ID
  - `faces` object[], nullable: Detected faces. Each entry includes face_id, name, and image. Online-meeting analyses may also include OCR name-assignment provenance (confidence, votes, samples, alternatives, is_local, source, inferred_from_prefix). In-vehicle analyses may name the selected driver's face "Driver", with source 'driver_selection' and reason ('clear_lead' or 'sole_candidate'); that is a role label, not a person's name. Untyped passthrough — extra keys are not filtered.
  - `fps` number, nullable: Frames per second
  - `frame_upload_progress` integer, nullable: Frame upload progress percentage
  - `frame_upload_status` string, nullable: Frame upload status
  - `frames_with_faces_count` integer, nullable: Frames with detected faces
  - `height` number, nullable: Video height in pixels
  - `highlight_segments` object[], nullable: Highlight video segments
  - `highlight_status` string, nullable: Highlight video status
  - `highlight_url` string, nullable: Highlight video URL
  - `id` string, nullable: Unique video identifier
  - `is_user` boolean, nullable: Whether uploaded by user
  - `media_source` string, nullable: Source type: youtube, dropbox, public_url, file_upload
  - `media_source_url` string, nullable: The URL the media was submitted with. For an upload this is a reference to the stored media, not guaranteed to be readable; use the media's `playback-url` endpoint to play it back.
  - `message` string, nullable: Status message
  - `model_id` string, nullable: Model used for processing
  - `multilingual` boolean: Whether mixed-language transcription was requested for this video's audio track. This is the INPUT you gave, not a detection result. `false` when it was not requested. When on, the lines that are not in the audio's main language are also translated into it once the audio completes (see `auto_translation`), billed as a translation on top of transcription.
  - `orientation` string, nullable: Video orientation (PORTRAIT/LANDSCAPE)
  - `overall_emotions` object, nullable: Overall emotion scores for video
  - `pdf_generation_timestamp` string, nullable: PDF generation timestamp
  - `pdf_status` string, nullable: PDF report status
  - `pdf_url` string, nullable: PDF report URL
  - `predefined_qa` object[], nullable: Predefined Q&A data
  - `personality_data` object[], nullable: Personality analysis data
  - `personality_processing` string, nullable: Personality processing progress
  - `personality_status` string, nullable: Personality analysis status
  - `process_status` union: Processing progress
    - number
    - object
  - `processed_seconds` number, nullable: Processing time in seconds
  - `processing_fps` integer, nullable: Reduced processing frame-rate tier (15/10/5/1, or 30 when picked automatically), or null for full/native fps
  - `processing_fps_auto` boolean, nullable: True when processing_fps was picked so the video fits the processing time limit, because the upload set none: full frame rate when it fits, else 30, else 15. False when the caller set it. Null on documents that predate the field.
  - `processing_fps_estimate_s` integer, nullable: Estimated processing time in seconds at processing_fps, or null when unknown
  - `video_type` string, nullable: Processing mode: 'generic', 'online_meeting', or 'auto' as submitted. Once the worker has run, an 'auto' submission is replaced by the mode it resolved to, so this reports what actually ran. Null on documents that predate the field. Open string (not the submit enum) so a stored value this backend version does not know still serializes.
  - `meeting_platform` string, nullable: Optional meeting-client hint (zoom, google_meet, teams, webex). Null when unknown or unset. Open string for the same reason as video_type.
  - `driver_position` string, nullable: Seat hint for video_type='in_vehicle': which half of the VIDEO FRAME the driver appears in ('left'/'right') — not the vehicle's drive side. Null when unset or on a non-in_vehicle video. Open string for the same reason as video_type.
  - `driver_forward_gaze` DriverForwardGaze: The driver's straight-ahead gaze direction in camera-relative degrees, in the same axes and sign as the gaze_yaw / gaze_pitch values returned for faces.
    - `yaw_deg` number, required: Horizontal angle in degrees, camera-relative, in the same axes and sign as the gaze_yaw values returned for faces. Range [-90, 90].
    - `pitch_deg` number, required: Vertical angle in degrees, camera-relative, in the same axes and sign as the gaze_pitch values returned for faces. Range [-60, 60].
  - `camera_mount` string, nullable: Camera-mount hint supplied at upload for video_type='in_vehicle' ('steering_column', 'dashboard_center', 'windshield' or 'unknown'). Null when not supplied. Open string for the same reason as video_type.
  - `driver_forward_gaze_prior` DriverForwardGazePrior: A prior for the driver's straight-ahead gaze direction in camera-relative degrees, in the same axes and sign as the gaze_yaw / gaze_pitch values returned for faces, with how confident you are in it.
    - `yaw_deg` number, required: Horizontal angle in degrees, camera-relative, in the same axes and sign as the gaze_yaw values returned for faces. Range [-90, 90].
    - `pitch_deg` number, required: Vertical angle in degrees, camera-relative, in the same axes and sign as the gaze_pitch values returned for faces. Range [-90, 90].
    - `confidence` number, required: How confident you are in this prior, greater than 0 and at most 1. A low-confidence prior may not be applied.
  - `driver_state` DriverState: Driver drowsiness and distraction results on GET /v2/videos/{id}. Null when driver-state analysis never ran (every video whose video_type is not in_vehicle).
    - `selection` DriverSelection: Which face is the driver, and why. Present whenever driver_state ran.
      - `driver_face_id` integer, nullable: Chosen driver face id, or null when none was chosen
      - `reason` string, nullable: clear_lead | sole_candidate | no_lead | no_candidates | no_geometry | region_empty (open string)
      - `scores` object, nullable: Candidate id → score. Keys are strings.
    - `faces` object, nullable: Metrics keyed by face id as a string. Values may exist for losing candidates.
  - `project_id` string, nullable: Associated project ID
  - `project_type` string, nullable: Type of the associated project (recruitment/product_testing/...), null for library videos
  - `psychologist_review` string, nullable: Psychologist review content
  - `psychologist_review_status` string, nullable: Psychologist review status
  - `share_status` boolean, nullable: Whether video is shared
  - `diarization` boolean, nullable: Whether diarization was enabled at upload time (defaults to true if absent from the stored document)
  - `has_transcript` boolean, nullable: Whether a transcript exists (or is being produced): our ASR ran, OR one was supplied and applied. Drive the transcript UI off THIS, not `transcription` — an imported call has transcription=false and a real transcript, so that flag hides one that is right there.
  - `speech_status` union: Speech transcription status
    - string
    - boolean
  - `start_millis` number, nullable: Start time in milliseconds
  - `text_emotion` boolean, nullable: Whether text emotion analysis was enabled at upload time (defaults to true if absent from the stored document)
  - `transcription` boolean, nullable: Whether transcription/ASR was enabled at upload time (defaults to true if absent from the stored document)
  - `status` string, nullable: Processing status
  - `stimuli` ResolvedStimulus[], nullable: Stimuli (what the viewer reacts to) in this video's time, sorted by start. null when the video has none, or when stimulus_link.status is not 'resolved'. An empty list means the linked stimuli all fall outside the video.
    - `id` string, required: Stable stimulus id.
    - `label` string, required: What appears.
    - `kind` string, required: The kind of stimulus.
    - `start_ms` integer, required: When it appears in this video, in milliseconds.
    - `end_ms` integer, nullable: When it ends in this video, in milliseconds.
    - `category` string, nullable: Optional grouping label of your own. 1-32 characters of A-Z, a-z, 0-9, '_', '.' or '-'; surrounding spaces are removed and case is kept.
    - `variant` string, nullable: Optional label for comparing versions of the same stimulus. 1-64 characters; surrounding spaces are removed and case is kept.
    - `response_window_ms` integer[], nullable: Optional [start, end]: two integers, in milliseconds after this stimulus starts, with 0 <= start < end <= 600000. A reaction that begins inside this window is attributed to this stimulus. When omitted, the default window applies.
    - `attribute_during_span` boolean, nullable: Optional. true also attributes to this stimulus a reaction that begins while it is on screen, between start_ms and end_ms. true is accepted only when end_ms is after start_ms. Omitted and false are the same value, returned as null.
    - `clipped` boolean: True when the end was cut to the video's length.
  - `stimulus_link` StimulusLinkView: Where the video's stimuli come from.
    - `source` 'track' | 'inline', required: A linked stimulus track, or stimuli set on the video.
    - `track_id` string, nullable: The linked track (source 'track').
    - `track_name` string, nullable: The linked track's name.
    - `offset_ms` integer, nullable: Where track time 0 falls in the video.
    - `status` 'resolved' | 'track_missing' | 'unavailable', required: 'resolved': stimuli is current. 'track_missing': the linked track no longer exists, so there are no stimuli. 'unavailable': the stimuli could not be read right now; retry.
    - `excluded_count` integer: Stimuli left out because they start outside the video, for example after the track was edited or the video trimmed.
  - `non_human_spans` NonHumanSpan[]: Known non-human audio, such as a voice assistant or music, in milliseconds of this video. Empty when none has been set. A span does not by itself remove a speaker from analysis results.
    - `start_ms` integer, required: When it starts, in milliseconds.
    - `end_ms` integer, required: When it ends, in milliseconds. After start_ms.
    - `role` 'system' | 'media', required: Who is speaking: "system" or "media".
    - `label` string, nullable: Optional name, 1-80 characters after surrounding spaces are removed.
  - `summary` union: Video summary or summary object
    - string
    - object
  - `tags` union[], nullable: Generalized media tags (demographic, survey, label, system). Discriminated union over value_type — see /v2/tag-keys for dimension metadata.
    - union
      - StringTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'string', required
        - `value_text` string, required
      - EnumTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'enum', required
        - `value_text` string, required
      - IntegerTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'integer', required
        - `value_int` integer, required
      - BoolTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'boolean', required
        - `value_bool` boolean, required
      - DateTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'date', required
        - `value_date` string, date-time, required
      - GeoTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'location_admin', required
        - `value_geo` GeoValue, required: Administrative-level location. lat/lng intentionally omitted in v1.
          - `country` string, nullable
          - `state` string, nullable
          - `city` string, nullable
      - SetTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'set', required
        - `value_text` string, required
      - NoneTag
        - `id` string, required
        - `key` string, required
        - `source` string, required
        - `created_at` string, date-time, required
        - `created_by` string, nullable
        - `value_type` 'none', required
  - `tags_map` object, nullable: Legacy tags_map (sample flag only). No new keys here — use the `tags` field instead.
  - `text_id` string, nullable: Associated text analysis ID
  - `thumbnail` string, nullable: Thumbnail image URL
  - `title` string, nullable: Video title
  - `total_frames_count` integer, nullable: Total frames count
  - `ui_request` boolean, nullable: Whether request came from UI
  - `url` string, nullable: Stored video URL. A reference to the stored media, not guaranteed to be readable: use `GET /v2/videos/{video_id}/playback-url` to play it back.
  - `use_case` string, nullable: What the recording is, as declared on upload ('interview'), or null when none was declared. Open string for the same reason as video_type.
  - `user_id` string, nullable: The user who created the item (the same value as `created_by`).
  - `created_by` string, nullable: The user who created the item. Never changes, including when the item is moved to a workspace.
  - `owner` MediaOwnerOut: Who owns a media item. Never carries an email address.
    - `kind` 'user' | 'workspace', required: `user`: an item owned by one person, its creator. `workspace`: an item owned by a team workspace, which its members can read. This says who owns the item only; a share link or other access to it is separate.
    - `id` string, required: The owner's id: the user's id, or the workspace's id.
    - `name` string, nullable: The workspace's name, or the creator's display name. Absent when it is not known.
  - `video_csv_url` string, nullable: Video-specific CSV analysis URL
  - `width` number, nullable: Video width in pixels
  - `youtube_url` string, nullable: YouTube URL if applicable

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-06** `bc15cec7e794`: 2 info
  - added the optional property `processing_fps_auto` to the response with the `200` status
  - added the optional property `processing_fps_estimate_s` to the response with the `200` status
- **2026-10-31** `bd825cd86e8c`: 5 info
  - added the optional property `auto_translation` to the response with the `200` status
  - added the optional property `expected_languages` to the response with the `200` status
  - added the optional property `languages` to the response with the `200` status
  - added the optional property `multilingual` to the response with the `200` status
  - …1 more
- **2026-10-07** `45bdd041d683`: 2 info
  - added the optional property `created_by` to the response with the `200` status
  - added the optional property `owner` to the response with the `200` status
- **2026-10-01** `72330e2229c7`: 8 info
  - added the optional property `camera_mount` to the response with the `200` status
  - added the optional property `driver_forward_gaze` to the response with the `200` status
  - added the optional property `driver_forward_gaze_prior` to the response with the `200` status
  - added the optional property `driver_state/anyOf[subschema #1: DriverState]/faces/anyOf[subschema #1]/additionalProperties/forward_gaze` to the response with the `200` status
  - …4 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/get.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)