Reports

  • A report resource represents a specific report instance, detailing the data period and the download URL.

  • The API supports get to retrieve metadata for a specific report and list to list reports generated for a given job.

  • Each report has properties like id, jobId, startTime, endTime, createTime, jobExpireTime, and downloadUrl that identify it and specify its creation and data time.

  • Reports are associated with a specific job, and the jobExpireTime indicates when the job will stop generating new reports, in which case a replacement may be available.

  • The downloadUrl property is where the report can be retrieved, and it's possible to use gzip compression to reduce the bandwidth needed for the download, by adding the Accept-Encoding: gzip header.

A report resource identifies a specific instance of a report. The resource identifies the period of time for which the report contains data as well as the URL from which the report can be downloaded.

Methods

The following table shows the methods that the API supports for report resources.

Methods
get Retrieves the metadata for a specific report.
list Lists reports that have been generated for the specified reporting job.

JSON resource representation

The JSON structure below shows the format of a report resource:

{
  "id": string,
  "jobId": string,
  "startTime": timestamp,
  "endTime": timestamp,
  "createTime": timestamp,
  "jobExpireTime": timestamp,
  "downloadUrl": string
}

Properties

The following table defines the properties that appear in this resource:

Properties
id string
The ID that YouTube assigns to uniquely identify the report. Each report is associated with a single job, though a job may be associated with many report IDs.
jobId string
The ID of the job that created this report.
startTime timestamp
The start of the time period that the report instance covers. The inclusive value is a timestamp in RFC3339 UTC "Zulu" format, accurate to microseconds. Example: "2015-10-02T15:01:23.045678Z".
endTime timestamp
The end of the time period that the report instance covers. The exclusive value is a timestamp in RFC3339 UTC "Zulu" format, accurate to microseconds. Example: "2015-10-02T15:01:23.045678Z".
createTime timestamp
The date and time that the job was created. The property value is a timestamp in RFC3339 UTC "Zulu" format, accurate to microseconds. Example: "2015-10-02T15:01:23.045678Z".
jobExpireTime timestamp
The date and time that the job that is associated with the report either expired or will expire. The property value is a timestamp in RFC3339 UTC "Zulu" format, accurate to microseconds. Example: "2015-10-02T15:01:23.045678Z".

This property has a value if either the report type that is associated with the report's job has been deprecated or reports generated for that job have not been downloaded for a prolonged period of time. The value marks the date after which YouTube will no longer generate new reports for the job.

If you have a job that identifies an expiration date, you should update your system to stop requesting the report by that date. In some cases, a replacement report may be available.
downloadUrl string
The URL from which the report can be downloaded. The property value has a maximum length of 1000 characters.

To retrieve the report, send an HTTP GET request to this URL. In the request, set the Authorization HTTP Request header, using your authorization token as the header value.

Using gzip

You can reduce the bandwidth needed to download reports by enabling gzip compression on download requests. While your application will need additional CPU time to uncompress API responses, the benefit of consuming fewer network resources usually outweighs that cost.

To receive a gzip-encoded response, set the Accept-Encoding HTTP request header to gzip as shown in the following example:

Accept-Encoding: gzip