YouTube Channel Reports

gethttps://d1iwal3igywepk.cloudfront.net/youtube

Your YouTube channel, read from the YouTube Data, Analytics and Reporting APIs once YouTube is connected (Setup → Data sync → YouTube). Use it to see how the channel grows, which videos earn views, subscribers and revenue, and where viewers find them. The key needs web:read and attribution:read.

The question it answers: "How is my YouTube channel doing, and which videos drive it?"

What you get

Field	What it means
`channel[]`	One row per day: `views`, `watch_minutes`, `subscribers_gained`, `subscribers_lost`, `subscribers_net`, thumbnail `impressions`, `impressions_ctr` and `subscriber_count`
`channel[].impressions_ctr`	Thumbnail click-through rate, 0–1, weighted by impressions. `null` on a day with no impressions
`channel[].subscriber_count`	The latest subscriber-count snapshot taken on or before that day. `null` before the first snapshot
`videos[]`	One row per video, totals for the range: views, watch minutes, average view percentage, net subscribers, likes, comments, shares, impressions and CTR. Ranked by views
`videos[].likes`	Net likes: removals are subtracted, so it can be negative
`trend[]`	One video's numbers per day. Needs `video_id`; empty without it
`traffic_sources[]`	Views and watch minutes per YouTube traffic source (search, suggested videos, external…), with each source's `share_of_views`
`search_terms[]`	What viewers typed in YouTube search before watching, with views, watch minutes and `share_of_views`. Top 50
`countries[]`	Views and watch minutes per viewer country (ISO 3166-1 alpha-2)
`devices[]`	Views and watch minutes per device type: `MOBILE`, `DESKTOP`, `TV`, `TABLET`, `GAME_CONSOLE`, `UNKNOWN_PLATFORM`
`retention[]`	Audience retention curve, 100 points: `elapsed_ratio` (position in the video), `audience_watch_ratio` (share of views still watching, above 1 on rewatched parts) and `relative_retention_performance` (0–1, against YouTube videos of similar length). One video with `video_id`; otherwise the average of long-form videos, weighted by lifetime views
`video_revenue[]`	Per video, from FullVision tracking: `visitors` who arrived through a link carrying the video URL in `utm_source`, and the `customers` and `revenue_cents` charged in the range to people who visited from that video first. `video_id` `''` groups YouTube visits whose link names no video. A customer reached through two videos counts in both

YouTube reports its numbers 2–3 days late, so the last days of a range are usually empty. Impressions start 30 days before the channel was connected. These are YouTube-wide numbers: plays of videos embedded on your site are the web-videos view, a different measurement.

search_terms, countries and devices come per calendar month: without video_id you get the months that overlap the range, whole. With video_id you get that video's lifetime. retention ignores the range.

Every block empty means YouTube is not connected yet or the first sync is still running.

Parameters

Parameter	What it does	When you'd use it
`from`, `to` / `range`	The window. Defaults to the last 28 days	Compare a quarter
`fields`	Blocks to return: `channel`, `videos`, `trend`, `traffic_sources`, `search_terms`, `countries`, `devices`, `retention`, `video_revenue`	`fields=videos` for the video list only
`video_id`	One video: filters `videos` and `traffic_sources`, switches `search_terms`, `countries`, `devices` and `retention` to that video; `trend` needs it	Follow one video's launch
`limit`	Rows of `videos` and `video_revenue`, 1–500, default 100	`limit=500` for a full catalogue

Authorization

AuthorizationBearer <token>

API key as Bearer token

In: header

Query Parameters

range?string

Preset date range. Canonical names (last_30_days, last_7_days, last_3_months, last_6_months, last_year, all_time, …) and dashboard short keys (30d, 7d, 3m, 6m, 1y, all) are both accepted. Mutually exclusive with from/to.

Value in

"last_7_days"
"last_14_days"
"last_28_days"
"last_30_days"
"last_90_days"
"current_month"
"this_month"
"last_3_months"
"last_6_months"
"last_year"
"all_time"
"7d"
"14d"
"28d"
"30d"
"90d"
"3m"
"6m"
"1y"
"all"

from?string

Custom start date (YYYY-MM-DD). Ignored if range is set.

Match^\d{4}-\d{2}-\d{2}$

to?string

Custom end date (YYYY-MM-DD). Ignored if range is set.

Match^\d{4}-\d{2}-\d{2}$

fields?string

Comma-separated response blocks to return. OMIT for every block of the resolved form (the default — this param only ever narrows a response, never widens one). The legal set is resolved AFTER form selection, so it depends on whether an addressing key was supplied: some blocks exist only on the single form, and a report whose resolved form declares none rejects fields with 400. An unknown or duplicated name is a 400 listing the legal blocks for that form.

video_id?string

One video: filters videos and traffic_sources, switches search_terms, countries, devices and retention to that video, required by trend.

limit?integer

videos and video_revenue blocks: rows to return (default 100, max 500).

Range1 <= value <= 500

Responses

YouTube channel, video and traffic-source numbers for the range

range*

channel?array<>

videos?array<>

trend?array<>

traffic_sources?array<>

search_terms?array<>

YouTube search terms (top 25 per pull): the channel's calendar months overlapping the range, or with video_id that video's lifetime. Top 50 rows.

countries?array<>

Views by viewer country: the channel's calendar months overlapping the range, or with video_id that video's lifetime. Top 50 rows.

devices?array<>

Views by device type: the channel's calendar months overlapping the range, or with video_id that video's lifetime. Top 50 rows.

retention?array<>

Audience retention curve: one video's with video_id, else the lifetime-views-weighted average of the channel's long-form videos. Not range-bound.

video_revenue?array<>

Per video, from FullVision tracking: distinct visitors in the range whose utm_source holds the video URL, and the customers and revenue charged in the range to people who visited from that video before the charge. A customer reached through two videos counts in both.

is_cached?boolean

True when this response came from the gateway's cache (a fresh hit or a stale serve) rather than being computed for this request. A stale serve returns data that was correct at last_refresh and triggers a background refresh.

age_s?number

Seconds since the served figures were computed. 0 when they were computed for this request.

last_refresh?string

ISO-8601 UTC timestamp of the computation that produced these figures — the value to render as an 'as of' marker.

get/youtube

curl -X GET "https://d1iwal3igywepk.cloudfront.net/youtube?range=last_28_days&fields=channel%2Cvideos"

Example Responses

{  "range": {    "from": "string",    "to": "string"  },  "channel": [    {      "date": "string",      "views": 0,      "watch_minutes": 0,      "subscribers_gained": 0,      "subscribers_lost": 0,      "subscribers_net": 0,      "impressions": 0,      "impressions_ctr": 0,      "subscriber_count": 0    }  ],  "videos": [    {      "video_id": "string",      "title": "string",      "published_at": "string",      "is_short": 0,      "views": 0,      "watch_minutes": 0,      "average_view_percentage": 0,      "subscribers_net": 0,      "likes": 0,      "comments": 0,      "shares": 0,      "impressions": 0,      "impressions_ctr": 0    }  ],  "trend": [    {      "date": "string",      "views": 0,      "watch_minutes": 0,      "average_view_percentage": 0,      "subscribers_net": 0,      "impressions": 0,      "impressions_ctr": 0    }  ],  "traffic_sources": [    {      "traffic_source_type": "string",      "views": 0,      "watch_minutes": 0,      "share_of_views": 0    }  ],  "search_terms": [    {      "term": "string",      "views": 0,      "watch_minutes": 0,      "share_of_views": 0    }  ],  "countries": [    {      "country": "string",      "views": 0,      "watch_minutes": 0,      "share_of_views": 0    }  ],  "devices": [    {      "device_type": "string",      "views": 0,      "watch_minutes": 0,      "share_of_views": 0    }  ],  "retention": [    {      "elapsed_ratio": 0,      "audience_watch_ratio": 0,      "relative_retention_performance": 0    }  ],  "video_revenue": [    {      "video_id": "string",      "title": "string",      "visitors": 0,      "customers": 0,      "revenue_cents": 0    }  ],  "is_cached": true,  "age_s": 0,  "last_refresh": "string"}

application/json