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):
- List the report types and pick one (e.g.
channel_basic_a3). - Create a job for it. The job lives in the YouTube channel's Google account.
- 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.
- List the job's reports and download the ones you need. Each report can be downloaded for 60 days after YouTube generates it.
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 type | Contents |
|---|---|
channel_basic_a3 | Views, engaged views, watch time, likes, comments, shares, subscribers by video, country, day, live/on-demand and subscribed status |
channel_province_a3 | The same by U.S. state |
channel_playback_location_a3 | Where videos were watched (watch page, embedded, channel, Shorts feed…) |
channel_traffic_source_a3 | Traffic sources and their detail |
channel_device_os_a3 | Device type and operating system |
channel_demographics_a1 | Age group and gender |
channel_sharing_service_a2 | Shares by service |
channel_annotations_a2 | Annotation metrics (legacy) |
channel_cards_a1 | Card impressions, clicks and click rate per card |
channel_end_screens_a2 | End screen element impressions, clicks and click rate |
channel_subtitles_a3 | Views by subtitle language |
channel_combined_a3 | Playback location, traffic source, device and OS together |
channel_reach_basic_a1 | Thumbnail impressions and click-through rate per video |
channel_reach_combined_a1 | Thumbnail 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_a2 | Playlist 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"}'
| Field | Type | Required | Description |
|---|---|---|---|
report_type_id | String | Yes | A channel or playlist report type. |
name | String | No | Up 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": truefeeds the thumbnail impressions of your Upload-Post analytics. If YouTube setsexpireTimeon 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. Withoutconfirm: trueit answers400 confirmation_required. Achannel_reach_basic_a1job (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. A502 youtube_write_outcome_unknownmeans 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'
| Name | Type | Required | Description |
|---|---|---|---|
created_after | String | No | RFC 3339 timestamp: only reports created after it (including corrected ones). |
start_time_at_or_after | String | No | Only reports whose data starts at or after it. |
start_time_before | String | No | Only 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) oryoutube_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 carriesretry_afterand, for daily limits,resets_at; theRetry-Afterheader 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.