# YouTube channel insights

> Daily metrics, top videos, and demographics for a YouTube channel.

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

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

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

Returns the channel's stored details and, from YouTube Analytics, its daily
metrics, top ten videos, and viewer demographics over a window. YouTube's
figures lag by two to three days, so the default window is the 28 days ending
three days ago. Needs the `yt-analytics.readonly` grant; a connection without it
returns `422 connection_expired` with "Reconnect YouTube to enable analytics".

**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. |
| `startDate` | `YYYY-MM-DD` |          | First day, UTC. Give both dates or neither. A window covers at most 365 days.     |
| `endDate`   | `YYYY-MM-DD` |          | Last day, UTC, before today and on or after startDate.                            |

`channel.subscribers` is `null` when the channel hides its subscriber count.
YouTube withholds demographics for channels with too few viewers, so
`audience` can be empty.

**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/channel-insights?accountId=00000000-0000-4000-8000-000000000003&startDate=2026-09-05&endDate=2026-10-02" \
  -H "Authorization: Bearer $ADELI_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/analytics/youtube/channel-insights?accountId=00000000-0000-4000-8000-000000000003&startDate=2026-09-05&endDate=2026-10-02", {
  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/channel-insights",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    params={
        "accountId": "00000000-0000-4000-8000-000000000003",
        "startDate": "2026-09-05",
        "endDate": "2026-10-02",
    },
)
print(response.json())
```

## Responses

### 200

```json
{
  "platform": "youtube",
  "accountId": "00000000-0000-4000-8000-000000000003",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "channel": { "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx", "title": "Bird Channel", "handle": "@birds", "avatarUrl": "https://yt3.ggpht.com/...", "subscribers": 1500, "views": 90000, "videos": 12 },
  "insights": {
    "startDate": "2026-09-05",
    "endDate": "2026-10-02",
    "daily": [
      { "date": "2026-10-02", "views": 600, "minutesWatched": 1100, "averageViewDurationSeconds": 70, "subscribersGained": 5, "subscribersLost": 1, "likes": 20, "comments": 2, "shares": 0 }
    ],
    "topVideos": [{ "videoId": "dQw4w9WgXcQ", "views": 400, "minutesWatched": 800, "averageViewDurationSeconds": 65, "likes": 15, "comments": 2 }],
    "audience": {
      "ageGender": [{ "ageGroup": "age25-34", "gender": "female", "percentage": 31.5 }],
      "countries": [{ "country": "US", "views": 750 }]
    }
  },
  "fetchedAt": "2026-10-05T12:00:00.000Z"
}
```

### 422

```json
{
  "error": {
    "code": "connection_expired",
    "message": "Reconnect YouTube to enable analytics"
  }
}
```