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

# Get Average Emotions

`GET /v2/videos/{video_id}/emotions/average`

## 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}/emotions/average`
- 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`

Calculate and retrieve average emotion scores for a video with optional face filtering.

This endpoint computes the average emotion percentages across all frames in a video.
When a face_id is provided, it calculates the average emotions for only that specific face.

**Behavior:**
- **Without face_id**: Returns overall average emotion score for entire video (all faces combined)
- **With face_id**: Calculates average emotion scores for the specified face

**Parameters:**
- `video_id`: Unique identifier for the video
- `face_id`: (Optional) Calculate average emotions for only this face ID

**Response:**
Returns emotion scores as percentages (values sum to 1.0):
- `angry`: Percentage of anger emotion
- `disgust`: Percentage of disgust emotion
- `fear`: Percentage of fear emotion
- `happy`: Percentage of happiness emotion
- `sad`: Percentage of sadness emotion
- `surprise`: Percentage of surprise emotion
- `neutral`: Percentage of neutral emotion

**Use Cases:**
- **Overall video analysis**: Understand the general emotional tone of the entire video
- **Individual tracking**: Track emotional patterns of specific people throughout the video
- **Comparative analysis**: Compare emotional profiles between different faces in the same video

**Example Usage:**
- Overall average: `GET /v2/videos/123/emotions/average`
- Face-specific: `GET /v2/videos/123/emotions/average?face_id=1`

**Note:** Face-specific calculations require the face to appear in at least one frame.

## Path parameters

- `video_id` string, required: The unique video ID of the video for which average emotions are to be calculated

## Query parameters

- `face_id` integer, nullable: Optional face ID to calculate average emotions for a specific face

## Response `200`

Successful Response

- EmotionScores: Emotion scores representing the intensity of each emotion. All scores are non-negative floats (``ge=0``) — model intensities, not counts.
  - `angry` number: Score for angry
  - `contempt` number: Score for contempt
  - `disgust` number: Score for disgust
  - `fear` number: Score for fear
  - `happy` number: Score for happy
  - `neutral` number: Score for neutral
  - `sad` number: Score for sad
  - `surprise` number: Score for surprise

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-22** `536bf48bb9fb`: 3 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API
  - the endpoint scheme security `BearerAuth` was added to the API
  - the endpoint scheme security `OAuth2Delegated` was added to the API
- **2026-08-20** `74ceee4a5c98`: 2 info
  - `query` request parameter `face_id` list-of-types was widened by adding types `null`
  - for the `query` request parameter `face_id`, the type was generalized from `integer` to no type

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/emotions/average/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)