Youtube Reports API

openapi: 3.1.0
info:
  title: YouTube Analytics Analytics Groups Reports API
  description: 'The YouTube Analytics API enables you to retrieve YouTube Analytics data for channels and content owners.

    Use this API to generate custom analytics reports, track video performance metrics, monitor audience engagement,

    and gain insights into viewer demographics and behavior patterns.


    ## Key Features

    - Retrieve channel and video performance metrics

    - Access audience demographics and geographic data

    - Monitor engagement metrics like likes, comments, and shares

    - Track revenue and ad performance data (for monetized content)

    - Generate custom date-range reports


    ## Authentication

    All API requests require OAuth 2.0 authentication with appropriate scopes.

    '
  version: 2.0.0
  contact:
    name: Google Developers
    url: https://developers.google.com/youtube/analytics
    email: youtube-api-support@google.com
  license:
    name: Creative Commons Attribution 3.0
    url: http://creativecommons.org/licenses/by/3.0/
    identifier: CC-BY-3.0
  termsOfService: https://developers.google.com/terms/
  x-logo:
    url: https://www.youtube.com/img/desktop/yt_1200.png
servers:
- url: https://youtubeanalytics.googleapis.com/v2
  description: YouTube Analytics API Production Server
security:
- OAuth2:
  - https://www.googleapis.com/auth/yt-analytics.readonly
tags:
- name: Reports
  description: Operations for querying YouTube Analytics report data
paths:
  /reports:
    get:
      operationId: youtubeAnalytics.reports.query
      summary: Youtube Query Analytics Reports
      description: Retrieves YouTube Analytics data for a channel or content owner. The report provides aggregated statistics for the specified dimensions and metrics over the date range. The ids parameter specifies the channel or content owner for which the report is being retrieved.
      tags:
      - Reports
      parameters:
      - name: ids
        in: query
        required: true
        description: Identifies the YouTube channel or content owner for which the report is being retrieved. To request data for a YouTube user, set the parameter value to channel==CHANNEL_ID where CHANNEL_ID specifies the unique YouTube channel ID. To request data for a YouTube CMS content owner, set the parameter value to contentOwner==OWNER_NAME.
        schema:
          type: string
        example: channel==UC_x5XG1OV2P6uZZ5FSM9Ttw
      - name: startDate
        in: query
        required: true
        description: The start date for fetching YouTube Analytics data in YYYY-MM-DD format. The API response will include data from this date up to and including the end date.
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - name: endDate
        in: query
        required: true
        description: The end date for fetching YouTube Analytics data in YYYY-MM-DD format. The value must be less than or equal to today's date.
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - name: metrics
        in: query
        required: true
        description: A comma-separated list of YouTube Analytics metrics, such as views or likes, dislikes. See the Available Reports document or the Metrics document for a list of reports that you can retrieve and the metrics available in each report.
        schema:
          type: string
        example: views,estimatedMinutesWatched,likes
      - name: dimensions
        in: query
        description: A comma-separated list of YouTube Analytics dimensions, such as video or country. See the Available Reports document for a list of reports that you can retrieve and the dimensions used for those reports.
        schema:
          type: string
        example: day
      - name: filters
        in: query
        description: A list of filters that should be applied when retrieving YouTube Analytics data. The Available Reports document identifies the dimensions that can be used to filter each report.
        schema:
          type: string
        example: example_value
      - name: maxResults
        in: query
        description: The maximum number of rows to include in the response. The maximum value is 200.
        schema:
          type: integer
          maximum: 200
        example: 25
      - name: sort
        in: query
        description: A comma-separated list of dimensions or metrics that determine the sort order for YouTube Analytics data. By default the sort order is ascending. Prefix with a minus sign (-) to indicate descending order.
        schema:
          type: string
        example: example_value
      - name: startIndex
        in: query
        description: An index of the first entity to retrieve. Use this parameter as a pagination mechanism along with the max-results parameter.
        schema:
          type: integer
          minimum: 1
        example: 10
      - name: currency
        in: query
        description: The currency to which financial metrics should be converted. The default value is USD (US Dollar). Specify the parameter value as an ISO 4217 currency code.
        schema:
          type: string
        example: example_value
      - name: alt
        in: query
        description: Data format for the response.
        schema:
          type: string
          enum:
          - json
        example: json
      responses:
        '200':
          description: Successful response containing YouTube Analytics data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              examples:
                YoutubeanalyticsReportsQuery200Example:
                  summary: Default youtubeAnalytics.reports.query 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    columnHeaders:
                    - name: Example Title
                      columnType: DIMENSION
                      dataType: CURRENCY
                    rows: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /jobs/{jobId}/reports:
    get:
      operationId: youtubeReporting.reports.list
      summary: Youtube List Reports
      description: Lists reports created by a specific reporting job. Each report covers a 24-hour period and includes a download URL for retrieving the report data.
      tags:
      - Reports
      parameters:
      - name: jobId
        in: path
        required: true
        description: The ID of the job whose reports are being listed.
        schema:
          type: string
        example: abc123def456
      - name: onBehalfOfContentOwner
        in: query
        description: The content owner's external ID on which behalf the user is acting on.
        schema:
          type: string
        example: example_value
      - name: createdAfter
        in: query
        description: If specified, only reports created after the specified date/time are returned.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: startTimeAtOrAfter
        in: query
        description: If specified, only reports covering data on or after this date are returned.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: startTimeBefore
        in: query
        description: If specified, only reports covering data before this date are returned.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: pageToken
        in: query
        description: A token identifying a page of results to return.
        schema:
          type: string
        example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
      - name: pageSize
        in: query
        description: The maximum number of items to return in the response.
        schema:
          type: integer
        example: 25
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListReportsResponse'
              examples:
                YoutubereportingReportsList200Example:
                  summary: Default youtubeReporting.reports.list 200 response
                  x-microcks-default: true
                  value:
                    reports:
                    - id: abc123def456
                      jobId: abc123def456
                      startTime: '2026-01-15T10:30:00Z'
                      endTime: '2026-01-15T10:30:00Z'
                      createTime: '2026-01-15T10:30:00Z'
                      downloadUrl: https://www.example.com
                      jobExpireTime: '2026-01-15T10:30:00Z'
                    nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /jobs/{jobId}/reports/{reportId}:
    get:
      operationId: youtubeReporting.reports.get
      summary: Youtube Get Report
      description: Gets the metadata for a specific report including its download URL.
      tags:
      - Reports
      parameters:
      - name: jobId
        in: path
        required: true
        description: The ID of the job that created the report.
        schema:
          type: string
        example: abc123def456
      - name: reportId
        in: path
        required: true
        description: The ID of the report to retrieve.
        schema:
          type: string
        example: abc123def456
      - name: onBehalfOfContentOwner
        in: query
        description: The content owner's external ID on which behalf the user is acting on.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
              examples:
                YoutubereportingReportsGet200Example:
                  summary: Default youtubeReporting.reports.get 200 response
                  x-microcks-default: true
                  value:
                    id: abc123def456
                    jobId: abc123def456
                    startTime: '2026-01-15T10:30:00Z'
                    endTime: '2026-01-15T10:30:00Z'
                    createTime: '2026-01-15T10:30:00Z'
                    downloadUrl: https://www.example.com
                    jobExpireTime: '2026-01-15T10:30:00Z'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ColumnHeader:
      type: object
      description: Describes a single column in an Analytics report response, including its name, type, and data type.
      properties:
        name:
          type: string
          description: The name of the dimension or metric.
          example: Example Title
        columnType:
          type: string
          description: The type of the column. Valid values are DIMENSION and METRIC.
          enum:
          - DIMENSION
          - METRIC
          example: DIMENSION
        dataType:
          type: string
          description: The type of data that the column contains. Valid values are STRING, INTEGER, FLOAT, and CURRENCY.
          enum:
          - CURRENCY
          - FLOAT
          - INTEGER
          - STRING
          example: CURRENCY
    ErrorResponse:
      type: object
      description: A standard error response returned by the YouTube Analytics API.
      properties:
        error:
          type: object
          description: The error details.
          properties:
            code:
              type: integer
              description: The HTTP status code of the error.
            message:
              type: string
              description: A human-readable description of the error.
            status:
              type: string
              description: The error status code.
            details:
              type: array
              description: A list of additional error details.
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: The type of the error detail.
                  reason:
                    type: string
                    description: The reason code for the error.
                  domain:
                    type: string
                    description: The domain in which the error occurred.
                  metadata:
                    type: object
                    description: Additional metadata about the error.
                    additionalProperties:
                      type: string
          example: example_value
    Report:
      type: object
      properties:
        id:
          type: string
          description: The server-generated ID of the report.
          example: abc123def456
        jobId:
          type: string
          description: The ID of the job that created this report.
          example: abc123def456
        startTime:
          type: string
          format: date-time
          description: The start of the time period that the report covers.
          example: '2026-01-15T10:30:00Z'
        endTime:
          type: string
          format: date-time
          description: The end of the time period that the report covers.
          example: '2026-01-15T10:30:00Z'
        createTime:
          type: string
          format: date-time
          description: The date and time when the report was created.
          example: '2026-01-15T10:30:00Z'
        downloadUrl:
          type: string
          description: The URL from which the report can be downloaded.
          example: https://www.example.com
        jobExpireTime:
          type: string
          format: date-time
          description: The date and time when the job creating this report will expire.
          example: '2026-01-15T10:30:00Z'
    QueryResponse:
      type: object
      description: Response to a successful YouTube Analytics query request containing the requested report data including column headers and rows of data.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtubeAnalytics#resultTable.
          default: youtubeAnalytics#resultTable
          example: youtube#video
        columnHeaders:
          type: array
          description: A list of objects that describe the columns in the report table. Each object in the list identifies a query dimension or metric and provides information about the data type of that dimension or metric.
          items:
            $ref: '#/components/schemas/ColumnHeader'
          example: []
        rows:
          type: array
          description: The list contains all rows of the result table. Each item in the list is an array that contains comma-delimited data corresponding to a single row of data. The order of the comma-delimited data fields will match the order of the columns listed in the columnHeaders field.
          items:
            type: array
            description: A single row of data in the report result set.
            items:
              description: A value in the row, either a string or number depending on the column type.
          example: []
    ListReportsResponse:
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/Report'
          description: The list of reports.
          example: []
        nextPageToken:
          type: string
          description: A token to retrieve the next page of results.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
  responses:
    Unauthorized:
      description: The request was not authenticated or the credentials are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The request was authenticated but the caller does not have permission to perform the requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for YouTube Analytics API
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/youtube: Manage your YouTube account
            https://www.googleapis.com/auth/youtube.readonly: View your YouTube account
            https://www.googleapis.com/auth/yt-analytics.readonly: View YouTube Analytics reports
            https://www.googleapis.com/auth/yt-analytics-monetary.readonly: View YouTube Analytics monetary reports
externalDocs:
  description: YouTube Analytics API Documentation
  url: https://developers.google.com/youtube/analytics