# YouTube video insights

> Watch metrics for specific YouTube videos.

Canonical: <https://www.tryadeli.com/docs/api/analytics/youtube-video-insights>

`GET https://app.tryadeli.com/api/v1/analytics/youtube/video-insights`

Authorization: `Bearer <API key>` — see [Authentication](https://www.tryadeli.com/docs/authentication)

Returns watch metrics for specific videos, or for the channel's 20 newest, over
the same kind of window as
[channel insights](https://www.tryadeli.com/docs/api/analytics/youtube-channel-insights). Needs
`yt-analytics.readonly`, like channel insights.

**Query parameters**

| Name        | Type         | Required | Description                                                                                                |
| ----------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `accountId` | `uuid`       | Yes      | A connected YouTube channel.                                                                               |
| `profileId` | `uuid`       |          | Optional, because accountId names its profile. If you pass both, they must agree.                          |
| `videoIds`  | `string`     |          | Comma-separated YouTube video ids (providerId from GET /api/v1/posts), at most 50. Omit for the 20 newest. |
| `startDate` | `YYYY-MM-DD` |          | Give both dates or neither; the default is the 28 days ending three days ago.                              |
| `endDate`   | `YYYY-MM-DD` |          |                                                                                                            |

A video YouTube has no figures for in the window comes back with every metric
`null`.

**Errors** — `401 unauthorized`, `400 invalid_request`, `404 account_not_found`,
`404 profile_not_found`, `422 connection_expired`,
`422 provider_not_configured`, `429 rate_limited`, `502 provider_error`.

## Request examples

**cURL**

```bash
curl --fail-with-body "https://app.tryadeli.com/api/v1/analytics/youtube/video-insights?accountId=00000000-0000-4000-8000-000000000003&videoIds=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $ADELI_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/analytics/youtube/video-insights?accountId=00000000-0000-4000-8000-000000000003&videoIds=dQw4w9WgXcQ", {
  headers: {
    Authorization: `Bearer ${process.env.ADELI_API_KEY}`,
  },
});
console.log(await response.json());
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://app.tryadeli.com/api/v1/analytics/youtube/video-insights",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    params={
        "accountId": "00000000-0000-4000-8000-000000000003",
        "videoIds": "dQw4w9WgXcQ",
    },
)
print(response.json())
```

## Responses

### 200

```json
{
  "platform": "youtube",
  "accountId": "00000000-0000-4000-8000-000000000003",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "insights": {
    "startDate": "2026-09-05",
    "endDate": "2026-10-02",
    "videos": [
      { "videoId": "dQw4w9WgXcQ", "views": 400, "minutesWatched": 800, "averageViewDurationSeconds": 65, "averageViewPercentage": 54.2, "likes": 15, "comments": 2, "shares": 1, "subscribersGained": 3 }
    ]
  },
  "fetchedAt": "2026-10-05T12:00:00.000Z"
}
```

### 404

```json
{
  "error": {
    "code": "account_not_found",
    "message": "YouTube account not found"
  }
}
```