YouTube Analytics

Access the YouTube Analytics API with managed OAuth authentication. Retrieve channel performance reports (views, watch time, subscribers, revenue) and manage analytics groups for aggregating videos, playlists, or channels.

Reference

Query Reports

GET /youtube-analytics/v2/reports?ids={channel_id}&startDate={start}&endDate={end}&metrics={metrics}

Required Parameters:

Parameter	Type	Description
`ids`	string	Channel identifier: `channel==MINE` or `channel==CHANNEL_ID`
`startDate`	string	Start date in `YYYY-MM-DD` format
`endDate`	string	End date in `YYYY-MM-DD` format
`metrics`	string	Comma-separated metrics (e.g., `views,likes,comments`)

Optional Parameters:

Parameter	Type	Description
`dimensions`	string	Comma-separated dimensions (e.g., `day`, `month`, `country`, `video`)
`filters`	string	Filters in format `dimension==value` (e.g., `country==US`)
`sort`	string	Sort field; prefix with `-` for descending (e.g., `-views`)
`maxResults`	integer	Maximum rows to return
`startIndex`	integer	1-based pagination start index
`currency`	string	ISO 4217 currency code for revenue metrics (default: USD)

Example - Daily views for a month:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-analytics/v2/reports?ids=channel==MINE&startDate=2025-03-01&endDate=2025-03-31&metrics=views,estimatedMinutesWatched,averageViewDuration&dimensions=day&sort=-views&maxResults=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Example - Monthly summary:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-analytics/v2/reports?ids=channel==MINE&startDate=2024-01-01&endDate=2024-12-01&metrics=views,likes,shares,subscribersGained,subscribersLost&dimensions=month&sort=-views')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": "day",
      "columnType": "DIMENSION",
      "dataType": "STRING"
    },
    {
      "name": "views",
      "columnType": "METRIC",
      "dataType": "INTEGER"
    }
  ],
  "rows": [
    ["2025-03-12", 4],
    ["2025-03-15", 2]
  ]
}

Common Metrics:

views - Total video views
likes - Total likes
dislikes - Total dislikes
comments - Total comments
shares - Total shares
estimatedMinutesWatched - Total watch time in minutes
averageViewDuration - Average view duration in seconds
subscribersGained - New subscribers gained
subscribersLost - Subscribers lost
averageViewPercentage - Average percentage of video watched
cardClickRate - Card click rate

Common Dimensions:

day - Daily aggregation (YYYY-MM-DD)
month - Monthly aggregation (YYYY-MM); endDate must align to 1st of month
country - ISO 3166-1 alpha-2 country code
video - Per-video breakdown
deviceType - Device type (DESKTOP, MOBILE, TABLET, TV, etc.)
operatingSystem - OS (ANDROID, IOS, WINDOWS, etc.)
liveOrOnDemand - LIVE or ON_DEMAND
subscribedStatus - SUBSCRIBED or UNSUBSCRIBED

List Groups

GET /youtube-analytics/v2/groups?mine=true

Or by specific IDs:

GET /youtube-analytics/v2/groups?id={group_id}

Parameters:

Parameter	Type	Description
`mine`	boolean	Set to `true` to retrieve all groups owned by authenticated user
`id`	string	Comma-separated group IDs to retrieve
`pageToken`	string	Token for paginating results

Response:

{
  "kind": "youtube#groupListResponse",
  "items": [
    {
      "kind": "youtube#group",
      "etag": "CQVfQEQY1xqZ2O8xKat5QfS2cik",
      "id": "JiAz5ne9Wwk",
      "snippet": {
        "title": "My Video Group",
        "publishedAt": "2026-05-04T22:02:12Z"
      },
      "contentDetails": {
        "itemType": "youtube#video"
      }
    }
  ],
  "nextPageToken": "..."
}

Create Group

POST /youtube-analytics/v2/groups
Content-Type: application/json

{
  "snippet": {
    "title": "My New Group"
  },
  "contentDetails": {
    "itemType": "youtube#video"
  }
}

Valid item types: youtube#video, youtube#playlist, youtube#channel, youtubePartner#asset

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "snippet": {"title": "Top Performers"},
    "contentDetails": {"itemType": "youtube#video"}
}).encode()
req = urllib.request.Request('https://api.maton.ai/youtube-analytics/v2/groups', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Update Group

PUT /youtube-analytics/v2/groups
Content-Type: application/json

{
  "id": "{group_id}",
  "snippet": {
    "title": "Updated Title"
  },
  "contentDetails": {
    "itemType": "youtube#video"
  }
}

Only the group title can be updated.

Delete Group

DELETE /youtube-analytics/v2/groups?id={group_id}

List Group Items

GET /youtube-analytics/v2/groupItems?groupId={group_id}

Response:

{
  "kind": "youtube#groupItemListResponse",
  "etag": "...",
  "items": [
    {
      "kind": "youtube#groupItem",
      "etag": "...",
      "groupId": "JiAz5ne9Wwk",
      "resource": {
        "kind": "youtube#video",
        "id": "VIDEO_ID"
      }
    }
  ]
}

Add Item to Group

POST /youtube-analytics/v2/groupItems
Content-Type: application/json

{
  "groupId": "{group_id}",
  "resource": {
    "kind": "youtube#video",
    "id": "{video_id}"
  }
}

Returns 201 on success, 204 if item already exists in group. Maximum 500 items per group.

Remove Item from Group

DELETE /youtube-analytics/v2/groupItems?id={group_item_id}

YouTube Analytics

Reference

Query Reports

List Groups

Create Group

Update Group

Delete Group

List Group Items

Add Item to Group

Remove Item from Group

Resources

On this page