YouTube Analytics Reports
Query the YouTube Analytics API for the channel connected to a profile with any of YouTube's official channel reports: views, watch time and engagement by day or month, country, U.S. state, city or DMA; subscribed vs. not subscribed viewers; live vs. on-demand; YouTube product; playback locations and embedding sites; traffic sources and the YouTube search terms that brought viewers; device type and operating system; age and gender; sharing services; audience retention; concurrent viewers of a live stream; top videos and top playlists; playlist reports; and membership cancellations.
Upload-Post checks every query against YouTube's report tables before sending it, so an invalid combination is rejected for free instead of spending your daily allowance, and repeats of the same query are answered from a cache. These endpoints follow the common rules of the YouTube endpoints.
Analytics reports are not generally available yet. Until they are, /analytics/query, /analytics/reports and /analytics/groups answer 503 Service Unavailable with error_code: "youtube_analytics_disabled", and /analytics/usage shows "enabled": false. The analytics Upload-Post already shows in Get analytics are not affected.
YouTube Analytics data is processed with a 48-72 hour delay: the most recent days may be missing or still change (YouTube: data freshness). Answers are cached for 12 hours (7 days when the whole range ended more than 5 days ago). There is no way to force a fresh read before the cache expires. For large volumes of data, use YouTube bulk reports, which do not use this allowance.
Endpoints
GET /api/uploadposts/youtube/analytics/query
GET /api/uploadposts/youtube/analytics/reports
GET /api/uploadposts/youtube/analytics/groups
GET /api/uploadposts/youtube/analytics/groups/{group_id}/items
GET /api/uploadposts/youtube/analytics/usage
Headers
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
Run a report: GET /analytics/query
The parameters are those of YouTube's reports.query, in snake_case. The report always covers the channel of user.
| Name | Type | Required | Description |
|---|---|---|---|
user | String | Yes | Profile username with a YouTube channel connected. |
start_date | String | Yes | YYYY-MM-DD (Pacific Time). |
end_date | String | Yes | YYYY-MM-DD. Dates after today are treated as today. With the month dimension both dates must be the 1st of a month. |
metrics | String | Yes | Comma-separated metrics, e.g. views,estimatedMinutesWatched,averageViewDuration. |
dimensions | String | No | Comma-separated dimensions, e.g. day, country, city, insightTrafficSourceDetail. |
filters | String | No | YouTube's syntax dimension==value joined with ;, e.g. video==dQw4w9WgXcQ;country==US. video and playlist accept up to 500 IDs separated by commas (add video to dimensions to get one row per video). A JSON object such as {"video": ["id1","id2"], "country": "US"} also works. |
sort | String | No | Comma-separated dimensions or metrics; - for descending (-views). Some reports require it (see below). |
max_results | Integer | No | Maximum rows. Required by the reports with a limit (city ≤ 250, top videos/playlists ≤ 200, detail reports ≤ 25). |
start_index | Integer | No | 1-based index of the first row, for paging with max_results. |
report | String | No | Report ID from the catalog. Optional: without it Upload-Post finds the matching report; with it you get a precise error if the query does not fit that report. |
Rules Upload-Post checks for you
These come from YouTube's channel reports; a query that breaks them is answered 400 youtube_analytics_unsupported_query with hints (the closest reports and what is missing), and spends nothing.
- The combination of dimensions, metrics and filters must be one of YouTube's channel reports.
province(as dimension or report) needs the filtercountry==US; the DMA report needscountry==USor a U.S.province.- City (
dimensions=city):sortis-viewsor-estimatedMinutesWatchedandmax_results≤ 250. - Traffic source detail (
dimensions=insightTrafficSourceDetail): filterinsightTrafficSourceTypewithYT_SEARCH(search terms),EXT_URL,RELATED_VIDEO,YT_CHANNEL,YT_OTHER_PAGE,SUBSCRIBER,ADVERTISING,HASHTAGS,SOUND_PAGEorWATCH_WITH;sort-viewsor-estimatedMinutesWatched;max_results≤ 25. - Playback location detail: filter
insightPlaybackLocationType==EMBEDDED, sort andmax_results≤ 25. - Traffic source with a
videofilter: number of videos × days in the range ≤ 50,000. - Top videos (
dimensions=video) and top playlists (dimensions=playlist):sortfrom the report's options andmax_results≤ 200. - Audience retention (
dimensions=elapsedVideoTimeRatio) and concurrent viewers: exactly one video in thevideofilter. liveOrOnDemandcannot be combined withaverageViewPercentage.
Not available
- Revenue and ads:
estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,cpm,playbackBasedCpm,adImpressions,monetizedPlaybacks, theadTypedimension (ad performance report) andcurrencyneed a YouTube permission (yt-analytics-monetary.readonly) that Upload-Post does not request. They are refused with 400youtube_analytics_monetary_not_available. - Content owner (CMS) reports (
channel,claimedStatus,uploaderType) are only for YouTube content partners: 400youtube_analytics_content_owner_only. - Deprecated metrics such as
uniques.
Example: top search terms of a video
curl -G https://api.upload-post.com/api/uploadposts/youtube/analytics/query \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'start_date=2026-10-01' \
--data-urlencode 'end_date=2026-10-31' \
--data-urlencode 'dimensions=insightTrafficSourceDetail' \
--data-urlencode 'metrics=views,estimatedMinutesWatched' \
--data-urlencode 'filters=video==dQw4w9WgXcQ;insightTrafficSourceType==YT_SEARCH' \
--data-urlencode 'sort=-views' \
--data-urlencode 'max_results=25'
Example: views by city
curl -G https://api.upload-post.com/api/uploadposts/youtube/analytics/query \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'start_date=2026-10-01' \
--data-urlencode 'end_date=2026-10-31' \
--data-urlencode 'dimensions=city' \
--data-urlencode 'metrics=views,estimatedMinutesWatched' \
--data-urlencode 'sort=-views' \
--data-urlencode 'max_results=50'
Successful Response (200 OK)
column_headers and rows are YouTube's result table as YouTube returns it.
{
"success": true,
"report": "traffic_source_detail",
"report_name": "Traffic source detail, incl. YouTube search terms (<= 25 results)",
"query": {
"start_date": "2026-10-01",
"end_date": "2026-10-31",
"metrics": ["views", "estimatedMinutesWatched"],
"dimensions": ["insightTrafficSourceDetail"],
"filters": {"insightTrafficSourceType": ["YT_SEARCH"], "video": ["dQw4w9WgXcQ"]},
"sort": ["-views"],
"max_results": 25
},
"column_headers": [
{"name": "insightTrafficSourceDetail", "columnType": "DIMENSION", "dataType": "STRING"},
{"name": "views", "columnType": "METRIC", "dataType": "INTEGER"},
{"name": "estimatedMinutesWatched", "columnType": "METRIC", "dataType": "INTEGER"}
],
"rows": [["how to upload to youtube", 1520, 3410], ["youtube api", 310, 802]],
"cached": false,
"cached_at": "2026-11-14T16:00:00Z",
"expires_at": "2026-11-15T04:00:00Z",
"data_note": "YouTube Analytics data is processed with a 48-72 hour delay; ..."
}
Report catalog: GET /analytics/reports
The 47 channel reports with, for each one, its dimensions, metrics, filters (with the rule: req all of them, exactly1, 1+, 0-1, 0+), sort options, row limit and notes. It does not call YouTube. The ad performance report is listed with "available": false.
curl -G https://api.upload-post.com/api/uploadposts/youtube/analytics/reports \
-H 'Authorization: Apikey your-api-key-here' --data-urlencode 'user=my-profile'
Analytics groups
YouTube Analytics groups (collections of videos or playlists you created in YouTube) can be used as the group filter of a report.
GET /analytics/groups?user=...— your groups (groups.list). Optionalids(up to 50, comma separated) andpage_token.GET /analytics/groups/{group_id}/items?user=...— the items of a group (groupItems.list).
Answers are the standard list shape (items, next_page_token) and are cached for 30 minutes. Creating or editing groups needs a YouTube permission Upload-Post does not request, so it is not offered.
Daily allowance
The YouTube Analytics API has its own daily quota, separate from uploads and from the YouTube management features. Every call to YouTube (a query not in the cache, a groups page) counts 1 request of your account's daily allowance; cached answers and refused queries count nothing. The allowance is small — 20 requests per day on paid plans and 2 on the free plan — and these limits may change. When the shared allowance is used up the endpoint answers 429 until midnight Pacific Time, and a burst of reports in the same minute can answer 429 youtube_analytics_quota_exhausted (retry in a minute); the analytics Upload-Post already shows in your dashboard are not affected.
curl https://api.upload-post.com/api/uploadposts/youtube/analytics/usage \
-H 'Authorization: Apikey your-api-key-here'
{
"success": true,
"plan": "paid",
"services": {
"analytics": {"used": 3, "limit": 20, "unit": "requests", "enabled": true},
"reporting": {"used": 12, "limit": 300, "unit": "requests", "enabled": true}
},
"resets_at": "2026-11-15T08:00:00Z",
"retry_after": 41230
}
Error Responses
All errors carry success: false, a readable error and a stable error_code.
- 400 Bad Request —
youtube_analytics_unsupported_query(withhints),youtube_analytics_monetary_not_available,youtube_analytics_content_owner_only,youtube_analytics_range_too_large,invalid_metrics,invalid_dimensions,invalid_filters,too_many_ids,invalid_sort,invalid_date,invalid_max_results,invalid_start_index,invalid_report,invalid_parameter,invalid_ids,invalid_group_id,missing_user,youtube_not_connected; or YouTube rejected the query (youtube_bad_request; YouTube's answer is kept for an hour, so the same query is not sent again in that time). - 401 Unauthorized —
youtube_reauth_required: reconnect the YouTube channel. - 403 Forbidden —
youtube_insufficient_scope: reconnect the channel to grant the YouTube Analytics permission. - 409 Conflict —
youtube_analytics_query_in_progress: the same query is running; retry in a few seconds. - 429 Too Many Requests —
youtube_daily_budget_exhausted(your account used its daily allowance;limitsays how much),youtube_shared_budget_exhausted(the allowance shared by all accounts is used up),youtube_analytics_quota_exhausted(YouTube's own quota is used up, too many reports this minute, or YouTube asked to slow down). The body carriesretry_afterand, for daily limits,resets_at; theRetry-Afterheader says the same. - 502 Bad Gateway —
youtube_upstream_errororyoutube_unreachable. - 503 Service Unavailable —
youtube_analytics_disabled(not generally available yet, see the note above),youtube_feature_disabled(YouTube management features temporarily off),youtube_analytics_unavailable(retry in a few minutes),youtube_token_refresh_failed. Uploads keep working.