---
title: "Get YouTube demographics"
method: GET
path: "/v1/analytics/youtube/demographics"
tags: ["Analytics"]
---

# Get YouTube demographics

`GET /v1/analytics/youtube/demographics`

Returns audience demographic insights for a YouTube channel, broken down by age, gender, and/or country.
Pass videoId to get the audience profile of a single video instead of the whole channel.
Age and gender values are viewer percentages (0-100). Country values are view counts.
Data is based on signed-in viewers only, with a 2-3 day delay. YouTube suppresses demographics
for videos with too few signed-in views, so low-traffic videos can return empty breakdowns.
Requires the Analytics add-on.

## Query parameters

- `accountId` string, required
- `videoId` string
- `breakdown` string
- `fromDate` string, date
- `toDate` string, date
- `startDate` string, date
- `endDate` string, date

## Response `200`

Demographic insights data

- YouTubeDemographicsResponse
  - `success` boolean
  - `accountId` string — The Zernio SocialAccount ID
  - `platform` string
  - `videoId` string — Present only when demographics are scoped to a single video
  - `title` string, nullable — Video title (video mode only)
  - `publishedAt` string, date-time, nullable — Video publish date (video mode only)
  - `demographics` object — Object keyed by breakdown dimension (age, gender, country)
  - `dateRange` object
    - `startDate` string
    - `endDate` string
  - `provisionalSince` string, date — Present only when the range reaches into YouTube's ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.
  - `note` string

## Other responses

- `400` — Bad request (invalid parameters or not a YouTube account)
- `401` — Unauthorized
- `402` — Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.
- `403` — Access denied to this account
- `404` — Account not found, or the video does not exist / does not belong to this YouTube channel
- `412` — YouTube Analytics scope not granted
- `502` — The platform returned a server error.
- `503` — An upstream service or database is temporarily unavailable. Retry after the indicated delay. A timed-out write may have completed upstream; check its outcome before resubmitting.

## Changes

- **2026-09-23** `dd3865482f9f` — 4 info
  - added the new optional `query` request parameter `fromDate`
  - added the new optional `query` request parameter `toDate`
  - `query` request parameter `endDate` was deprecated
  - `query` request parameter `startDate` was deprecated
- **2026-09-16** `3e6ddf2a99ea` — 2 info
  - added the optional property `details/budgetScope` to the response with the `502` status
  - added the optional property `details/budgetScope` to the response with the `503` status
- **2026-09-15** `0dba7d004d75` — 4 info
  - added the optional property `details/quotaExhausted` to the response with the `502` status
  - added the optional property `details/quotaExhausted` to the response with the `503` status
  - added the optional property `details/quotaScope` to the response with the `502` status
  - added the optional property `details/quotaScope` to the response with the `503` status
- **2026-09-10** `e70ed06e7150` — 2 info
  - added the non-success response with the status `502`
  - added the non-success response with the status `503`

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/analytics/youtube/demographics/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/dd3865482f9f?raw)