Skip to main content

YouTube Bulk Reports

The YouTube Reporting API is YouTube's way to get large amounts of channel data. Instead of running queries, you schedule a reporting job for a report type; YouTube then generates one CSV file per day for the channel, which you list and download. It does not use the Analytics reports allowance, and it has data the Analytics API does not offer, such as thumbnail impressions and click-through rate (channel_reach_basic_a1, channel_reach_combined_a1), end screen and card elements, and subtitle languages.

How it works (YouTube: bulk reports):

  1. List the report types and pick one (e.g. channel_basic_a3).
  2. Create a job for it. The job lives in the YouTube channel's Google account.
  3. About 48 hours later the first reports appear; they cover the 30 days before the job was created. After that, a new report arrives every day.
  4. List the job's reports and download the ones you need. Each report can be downloaded for 60 days after YouTube generates it.
Not generally available yet

Bulk reports are not generally available yet. Until they are, every endpoint on this page answers 503 Service Unavailable with error_code: "youtube_reporting_disabled". The thumbnail impressions Upload-Post already shows in Get analytics are not affected.

Reports are CSV files with one row per combination of dimensions and day (Pacific Time), without totals and without rows whose metrics are all zero. Some columns are numeric codes (traffic source, device type…); YouTube documents them in dimensions and metrics. When YouTube corrects past data it publishes a new report with the same startTime and a newer createTime: use the newest one for each day. Bulk reports have no revenue data for channels.

Endpoints​

GET    /api/uploadposts/youtube/reporting/report-types
GET /api/uploadposts/youtube/reporting/jobs
POST /api/uploadposts/youtube/reporting/jobs
GET /api/uploadposts/youtube/reporting/jobs/{job_id}
DELETE /api/uploadposts/youtube/reporting/jobs/{job_id}
GET /api/uploadposts/youtube/reporting/jobs/{job_id}/reports
GET /api/uploadposts/youtube/reporting/jobs/{job_id}/reports/{report_id}
GET /api/uploadposts/youtube/reporting/jobs/{job_id}/reports/{report_id}/download

All of them take user (profile username with a YouTube channel connected), in the query string or the JSON body, and the header Authorization: Apikey your-api-key-here. Lists return one page per call (items, next_page_token and page_info, which is null for these lists; send next_page_token back as page_token; optional page_size 1-500). They follow the common rules of the YouTube endpoints.

Report types​

GET /reporting/report-types lists what YouTube can generate for the channel (reportTypes.list). can_create_job is true for the channel and playlist types you can schedule. The channel report types documented by YouTube:

Report typeContents
channel_basic_a3Views, engaged views, watch time, likes, comments, shares, subscribers by video, country, day, live/on-demand and subscribed status
channel_province_a3The same by U.S. state
channel_playback_location_a3Where videos were watched (watch page, embedded, channel, Shorts feed…)
channel_traffic_source_a3Traffic sources and their detail
channel_device_os_a3Device type and operating system
channel_demographics_a1Age group and gender
channel_sharing_service_a2Shares by service
channel_annotations_a2Annotation metrics (legacy)
channel_cards_a1Card impressions, clicks and click rate per card
channel_end_screens_a2End screen element impressions, clicks and click rate
channel_subtitles_a3Views by subtitle language
channel_combined_a3Playback location, traffic source, device and OS together
channel_reach_basic_a1Thumbnail impressions and click-through rate per video
channel_reach_combined_a1Thumbnail impressions and CTR by traffic source, device and OS
playlist_basic_a2, playlist_province_a2, playlist_playback_location_a2, playlist_traffic_source_a2, playlist_device_os_a2, playlist_combined_a2Playlist reports

Newer versions YouTube publishes later are accepted as well. Content owner (CMS) and system-managed reports are not available for channels.

Create a job​

curl -X POST https://api.upload-post.com/api/uploadposts/youtube/reporting/jobs \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"user": "my-profile", "report_type_id": "channel_reach_combined_a1"}'
FieldTypeRequiredDescription
report_type_idStringYesA channel or playlist report type.
nameStringNoUp to 100 characters. Default: upload-post <report type>.

201 Created:

{
"success": true,
"job": {"id": "8a4f1c2e-...", "reportTypeId": "channel_reach_combined_a1",
"name": "upload-post channel_reach_combined_a1", "createTime": "2026-11-14T16:00:00Z"},
"note": "YouTube generates one report per day. The first ones appear within about 48 hours ..."
}

A channel can have one job per report type (a second one answers 409 youtube_reporting_job_exists with the existing job) and up to 20 jobs through Upload-Post (409 youtube_reporting_job_limit). If the answer is 502 youtube_write_outcome_unknown, YouTube did not confirm in time and the job may exist: list the jobs before trying again (it is never resent automatically).

List, read and delete jobs​

  • GET /reporting/jobs — the channel's jobs (jobs.list). A job marked "used_by_upload_post": true feeds the thumbnail impressions of your Upload-Post analytics. If YouTube sets expireTime on a job (deprecated report type, or no reports downloaded for a long time), create a new one.
  • GET /reporting/jobs/{job_id} — one job.
  • DELETE /reporting/jobs/{job_id} with {"user": "my-profile", "confirm": true} — stops YouTube from generating that report. Without confirm: true it answers 400 confirmation_required. A channel_reach_basic_a1 job (the one Upload-Post uses for thumbnail impressions in your analytics) cannot be deleted here (409 youtube_reporting_job_in_use); Upload-Post reads the job first (1 request) to check it. A 502 youtube_write_outcome_unknown means the job may already be deleted: list the jobs to check.

List and download reports​

curl -G https://api.upload-post.com/api/uploadposts/youtube/reporting/jobs/8a4f1c2e-.../reports \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'created_after=2026-11-01T00:00:00Z'
NameTypeRequiredDescription
created_afterStringNoRFC 3339 timestamp: only reports created after it (including corrected ones).
start_time_at_or_afterStringNoOnly reports whose data starts at or after it.
start_time_beforeStringNoOnly reports whose data starts before it.
{
"success": true,
"items": [
{"id": "4317112913", "jobId": "8a4f1c2e-...", "startTime": "2026-11-10T08:00:00Z",
"endTime": "2026-11-11T08:00:00Z", "createTime": "2026-11-12T10:21:33Z",
"download_path": "/api/uploadposts/youtube/reporting/jobs/8a4f1c2e-.../reports/4317112913/download"}
],
"next_page_token": null,
"page_info": null,
"cached": false
}

Download a report (the response is the CSV file, streamed):

curl -G https://api.upload-post.com/api/uploadposts/youtube/reporting/jobs/8a4f1c2e-.../reports/4317112913/download \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' -o report.csv

The response headers X-Report-Start-Time and X-Report-End-Time give the period the file covers. Files larger than 100 MB are not served (413 youtube_reporting_report_too_large), and an account can download up to 2 reports at the same time (429 youtube_reporting_downloads_busy). If a download is cut halfway (by YouTube or by the size limit), the connection is closed with an error instead of ending normally: never treat a download that did not finish cleanly as a complete CSV.

GET /reporting/jobs/{job_id}/reports/{report_id} returns one report's metadata.

Daily allowance​

Every call to YouTube counts 1 request of your account's daily allowance for bulk reports (a download counts 2: the report's metadata and the file); cached lists count nothing. 300 requests per day on paid plans and 30 on the free plan; these limits may change. Check them with GET /youtube/analytics/usage.

Error Responses​

All errors carry success: false, a readable error and a stable error_code.

  • 400 Bad Request — invalid_report_type_id, invalid_name, invalid_job_id, invalid_report_id, invalid_timestamp, invalid_page_token, invalid_page_size, confirmation_required, invalid_json, missing_user, youtube_not_connected; or YouTube rejected the call (youtube_bad_request, e.g. an unknown or deprecated report type).
  • 401 Unauthorized — youtube_reauth_required: reconnect the YouTube channel.
  • 403 Forbidden — youtube_insufficient_scope (reconnect to grant the YouTube Analytics permission) or youtube_forbidden.
  • 404 Not Found — the job or report does not exist for this channel.
  • 409 Conflict — youtube_reporting_job_exists, youtube_reporting_job_limit, youtube_reporting_job_in_use.
  • 413 Payload Too Large — youtube_reporting_report_too_large.
  • 429 Too Many Requests — youtube_daily_budget_exhausted, youtube_shared_budget_exhausted, youtube_reporting_quota_exhausted, youtube_reporting_downloads_busy. The body carries retry_after and, for daily limits, resets_at; the Retry-After header says the same.
  • 502 Bad Gateway — youtube_write_outcome_unknown (see above), youtube_reporting_bad_download_url, youtube_upstream_error, youtube_unreachable.
  • 503 Service Unavailable — youtube_reporting_disabled (not generally available yet, see the note above), youtube_feature_disabled (YouTube management features temporarily off), youtube_analytics_unavailable, youtube_token_refresh_failed. Uploads keep working.