YouTube automatically generates a set of system-managed ad revenue reports for content owners that have access to the corresponding reports in [Creator Studio](http://studio.youtube.com/). These reports are designed to provide programmatic access to data that is also available in manually downloadable reports accessible in the [Reports menu](https://support.google.com/youtube/answer/7648605) of the YouTube Creator Studio. > [!NOTE] > **Note:** The API provides access to a different set of reports than Creator Studio, though the reports contain similar data. API reports might have different fields and also use different field names than Creator Studio reports. Since YouTube automatically generates system-managed reports, the process for retrieving these reports is different than for the YouTube Analytics bulk data reports available through the API. ## Retrieving reports The following steps explain how to retrieve system-managed reports through the API. ### Step 1: Retrieve authorization credentials All YouTube Reporting API requests must be authorized. The [Authorization guide](https://developers.google.com/youtube/reporting/guides/authorization) explains how to use the OAuth 2.0 protocol to retrieve authorization tokens. YouTube Reporting API requests use the following authorization scopes: | Scope | Description | |---|---| | https://www.googleapis.com/auth/yt-analytics.readonly | View YouTube Analytics reports for your YouTube content. This scope provides access to user activity metrics, like view counts and rating counts. | | https://www.googleapis.com/auth/yt-analytics-monetary.readonly | View YouTube Analytics monetary reports for your YouTube content. This scope provides access to user activity metrics and to estimated revenue and ad performance metrics. |
### Step 2: Retrieve the job ID for the selected report Call the `jobs.list` method to retrieve a list of system-managed jobs. Set the [`includeSystemManaged`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs/list#includeSystemManaged) parameter to `true`. The [`reportTypeId`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs#reportTypeId) property in each returned `Job` resource identifies the type of system-managed report associated with that job. Your application needs the [`id`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs#id) property value from the same resource in the following step. The [Reports](https://developers.google.com/youtube/reporting/v1/reports/system_managed/reports) document lists available reports, their report type IDs, and the fields they contain. You can also use the [`reportTypes.list`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/reportTypes/list) method to retrieve a list of supported report types. ### Step 3: Retrieve the report's download URL Call the `jobs.reports.list` method to retrieve a list of reports created for the job. In the request, set the [`jobId`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#jobId) parameter to the job ID of the report that you want to retrieve. You can filter the list of reports using any or all of the following parameters: - Use the [`createdAfter`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to indicate that the API should only return reports created after a specified time. This parameter can be used to ensure that the API only returns reports that you have not already processed. - Use the [`startTimeBefore`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeBefore) parameter to indicate that the API response should only contain reports if the earliest data in the report is before the specified date. Whereas the `createdAfter` parameter pertains to the time the report was created, this date pertains to the data in the report. - Use the [`startTimeAtOrAfter`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeAtOrAfter) parameter to indicate that the API response should only contain reports if the earliest data in the report is on or after the specified date. Like the `startTimeBefore` parameter, this parameter value corresponds to the data in the report and not the time the report was created. The API response contains a list of `Report` resources for that job. Each resource refers to a report that contains data for a unique period. - The resource's [`startTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [`endTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) properties identify the time period that the report's data covers. - The resource's [`downloadUrl`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#downloadUrl) property identifies the URL from which the report can be fetched. - The resource's [`createTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) property specifies the date and time when the report was generated. Your application should store this value and use it to determine whether previously downloaded reports have changed. ### Step 4: Download the report Send an HTTP GET request to the `downloadUrl` obtained in step 4 to retrieve the report. ## Processing reports ### Best practices Applications that use the YouTube Reporting API should *always* follow these practices: - Use a report's header row to determine the ordering of the report's columns. For example, do not assume that [views](https://developers.google.com/youtube/reporting/v1/reports/metrics#views) will be the first metric returned in a report just because it is the first metric listed in a report description. Instead, use the report's header row to determine which column contains that data. - Keep a record of the reports you have downloaded to avoid repeatedly processing the same report. The following list suggests a couple of ways to do that. - When calling the [`reports.list`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method, use the [createdAfter](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to only retrieve reports created after a certain date. (Omit the `createdAfter` parameter the first time you retrieve reports.) Each time you retrieve and successfully process reports, store the timestamp corresponding to the [date and time](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when the newest of those reports was created. Then, update the `createdAfter` parameter value on each successive call to the [`reports.list`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method to ensure that you are only retrieving new reports, including new reports with backfilled data, each time you call the API. As a safeguard, before retrieving a report, also check to ensure that the report's [ID](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) is not already listed in your database. - Store the [ID](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) for each report that you have downloaded and processed. You can also store additional information like the [date and time](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when each report was generated or the report's [`startTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [`endTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime), which together identify the period for which the report contains data. For reports that retrieve bulk data for YouTube Analytics, each job will likely have many reports since each report contains data for a 24-hour period. System-managed jobs that cover longer time periods will have fewer reports. Use the report ID to identify reports that you still need to download and import. However, if two new reports have the same [`startTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [`endTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) property values, only import the report with the newer [`createTime`](https://developers.google.com/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) value. ### Report characteristics API reports are versioned CSV (comma-separated values) files that have the following characteristics: - Each report contains data for a unique period lasting from 12:00 AM Pacific time on the report's start date through 11:59 PM Pacific time on the report's end date. - Report data is not sorted.