--- title: "Get Video Moments Api" method: GET path: "/v2/videos/{video_id}/moments" tags: ["Video Emotion API"] --- # Get Video Moments Api `GET /v2/videos/{video_id}/moments` ## 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}/moments` - 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` Notable moments in a processed video, per face or speaker. Same authorization as other video GETs (owner, admin, shared, or sample). Moments are computed asynchronously once the video, its audio and its transcript have finished processing, and again after edits that change them (face merges, speaker links, linked people, reprocessing). This call never waits for that: - `status: ready` returns the moments. With `stale: true` the video changed since they were computed; these are the previous moments and a recomputation is queued. - `status: computing` means the first computation is queued or running. Poll again. - `status: failed` means the last computation failed for the video as it is now. - `status: unavailable` means the video has not finished processing, or Moments has not been requested for it. In the second case `reason` is `not_requested`; request it with `POST /v2/videos/{video_id}/moments/request`. Moments already computed for a video are still returned here, but the AI insights conversation does not use them until Moments has been requested for the video. `coverage` says, per subject and kind, whether that kind of moment could be looked for. No moments of a kind means none happened only where its coverage is `measured`. Join `moments[].subject` to `subjects[].id` for the face, speaker and linked person. New kinds and coverage reasons may appear at any time; treat unknown values as opaque. `generation` and `profile_version` say which computation these moments belong to. Compare them together with `computed_at`: a recomputation can leave `generation` and `profile_version` unchanged while `computed_at` moves. `profile_version` is the same value as `profile.version` when a profile is present. `visibility` says when each face was on screen, as half-open spans of video time; time outside every span is time the face was not visible. `uninterrupted: false` means brief absences inside a span were joined over. A reaction whose response window includes time the face was not visible carries `evidence.partly_seen: true`. `visibility` is null when it is not included with these moments: an older video or result, no usable visibility data, or left out to keep the result within its size limit. Null never means fully seen, and a subject missing from it has unknown visibility. ## Path parameters - `video_id` string, required: The unique video ID of the video to fetch moments for ## Response `200` Successful Response - VideoMomentsResponse: Moments for a video. `status` is `ready` (moments below), `computing` (first computation in progress; poll again), `failed` (the last computation failed for the current inputs) or `unavailable` (the video has not finished processing, or Moments was not requested for it). `stale` is true when the video changed since the moments were computed; the previous moments are returned while they are recomputed. - `video_id` string, required - `status` string, required: `ready`, `computing`, `failed` or `unavailable`. - `reason` string, nullable: Why `status` is `unavailable` when the video is complete: `not_requested` means Moments has not been requested for this video (see `POST /v2/videos/{video_id}/moments/request`). Null otherwise, including while the video is still processing. - `stale` boolean: True when a recomputation is pending for newer inputs. - `generation` integer, nullable: Which computation these moments belong to. Null when no moments are returned. Compare it together with `profile_version` and `computed_at`; it does not change on every recomputation. - `profile_version` string, nullable: Analysis profile version these moments were computed with, the same value as `profile.version` when a profile is present. Null when no moments are returned. - `moments` Moment[] - `id` string, required: Id of this moment. A later computation may assign a new id. `GET /v2/videos/{video_id}/moments/resolve` follows an id from an earlier computation to the current one, or reports that it is gone or unknown. Ids from older computations may be reported as unknown. - `kind` string, required: What happened, for example `eye_closure.microsleep` or `sentiment_flip`. - `subject` string, required: The subject it belongs to; join with `subjects[].id`. - `subject_resolution` string, required: How the subject was identified: `face`, `speaker` or `person`. - `baseline_source` string, nullable: Which baseline the deviation was measured against, when one was used. - `start_ms` integer, required - `end_ms` integer, required - `duration_ms` integer, required: Observed duration, in milliseconds. - `resolution_ms` integer, required - `modalities` MomentSpan[] - `modality` string, required: `face`, `voice` or `words`. - `start_ms` integer, required: Start, in milliseconds of video time. - `end_ms` integer, required: End, in milliseconds of video time. - `resolution_ms` integer, required: Time resolution of this modality, in milliseconds. - `anchor` MomentAnchor: What a moment responds to: a transcript sentence or a stimulus. - `kind` string, required: `sentence` or `stimulus`. - `id` string, required: The sentence or stimulus id. - `start_ms` integer, required - `end_ms` integer, required - `confidence` number, nullable: 0-1, when calibrated. - `score` number, required: Relative importance used to rank moments. - `evidence` object: Kind-specific measurements. `contaminated` is `true` when some of the voice or words evidence overlapped known non-human audio; it is absent otherwise. - `evidence_quality` string[]: Which evidence overlapped known non-human audio, such as a voice assistant or music: `audio_overlap:voice` and/or `audio_overlap:words`, in that order. Empty when none did, and on moments computed before this field existed. - `source_events` string[]: Ids of the signal events it was built from. - `coverage` MomentCoverage[] - `subject` string, required - `kind` string, required - `status` string, required: `measured`, `partial` or `unavailable`. - `reason` string, nullable: Why coverage is partial or unavailable. - `observed_s` number: Seconds in which the kind could be observed. - `detail` string, nullable - `detected_count` integer, nullable: Set when not every detected moment of this kind is listed (reason `cap_reached`): how many were detected for this subject. - `retained_count` integer, nullable: Set together with `detected_count`: how many of those moments are listed in `moments`. - `stimulus_coverage` StimulusCoverage[] - `subject` string, required - `stimulus_id` string, required - `status` string, required - `reason` string, nullable - `observed_s` number: Seconds of the stimulus's response window in which the subject could be observed. For a subject listed in `visibility`, this can instead be the seconds of that window in which its face was visible. - `counts` object: Number of moments per kind. - `visibility` SubjectVisibility[], nullable: When each face was visible, one entry per subject. A subject not listed has unknown visibility. Null when visibility is not included with these moments. - `subject` string, required: The subject; join with `subjects[].id`. - `visible_spans` VisibleSpan[]: When the face was visible, in order and never overlapping. Time outside every span is time the face was not visible. Empty when the face was never visible. - `start_ms` integer, required: Start, in milliseconds of video time (inclusive). - `end_ms` integer, required: End, in milliseconds of video time (exclusive). - `visible_ms` integer, required: Total visible time, in milliseconds: the sum of `visible_spans`. - `uninterrupted` boolean, required: True when each span is continuous visibility. False when brief absences inside a span were joined over, so a span alone does not prove the face was visible throughout it. - `profile` MomentsProfile: The analysis profile the moments were computed with. - `id` string, nullable: For example `conversation`, `sales` or `in_vehicle`. - `version` string, nullable - `schema_version` string, nullable: Version of the moments result format. - `safety_kinds` string[], nullable: Kinds of moment this profile treats as safety-relevant and ranks ahead of the others; empty when it has none. Null for moments computed before this was reported. - `subjects` MomentSubject[] - `id` string, required: `face:{face_id}` or `speaker:{speaker_id}`. - `face_id` string, nullable - `speaker_id` string, nullable - `person_id` string, nullable: The linked project person, if any. - `is_driver` boolean, nullable: Set on in-vehicle videos for the driver. - `role` string, nullable: The speaker's role, for example `agent` or `customer`. - `computed_at` string, date-time, nullable: When these moments were computed. ## Other responses - `422`: Validation Error ## Changes - **2026-10-31** `bd825cd86e8c`: 1 info - added the optional property `reason` to the response with the `200` status - **2026-10-01** `72330e2229c7`: 1 info - endpoint added [Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/moments/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/9c4d258def38?raw)