Youtube Analytics Groups API

openapi: 3.2.0
info:
  title: YouTube Analytics Analytics Groups API
  description: The YouTube Analytics API enables you to retrieve YouTube Analytics data for channels and content owners.
  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: Analytics > Groups
  description: Operations for managing analytics group definitions
paths:
  /groups:
    get:
      tags:
      - Analytics > Groups
      operationId: listAnalyticsGroups
      summary: Youtube List Analytics Groups
      description: 'Returns a collection of analytics groups that match the API request parameters.

        Groups allow you to aggregate data for multiple channels or videos to analyze

        combined performance metrics.'
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupListExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupId'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/AccessToken'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: Successful response containing list of analytics groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListResponse'
              examples:
                SuccessfulGroupListExample:
                  $ref: '#/components/examples/SuccessfulGroupListExample'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
    post:
      tags:
      - Analytics > Groups
      operationId: createAnalyticsGroup
      summary: Youtube Create Analytics Group
      description: 'Creates a new analytics group. Groups enable you to aggregate analytics data

        for multiple channels or videos, making it easier to analyze combined

        performance across related content.'
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupCreateExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreateRequest'
            examples:
              GroupCreateRequestExample:
                $ref: '#/components/examples/GroupCreateRequestExample'
      responses:
        '200':
          description: Successfully created analytics group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                SuccessfulGroupCreateExample:
                  $ref: '#/components/examples/SuccessfulGroupCreateExample'
        '400':
          description: Bad request - invalid group data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestErrorExample:
                  $ref: '#/components/examples/BadRequestErrorExample'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
  /groups/{groupId}:
    get:
      tags:
      - Analytics > Groups
      operationId: getAnalyticsGroup
      summary: Youtube Get Analytics Group
      description: 'Retrieves a specific analytics group by its unique identifier.

        Returns detailed information about the group including its title,

        content details, and associated metadata.'
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupCreateExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupIdPath'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: Successful response containing the analytics group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                SuccessfulGroupCreateExample:
                  $ref: '#/components/examples/SuccessfulGroupCreateExample'
        '404':
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
    put:
      tags:
      - Analytics > Groups
      operationId: updateAnalyticsGroup
      summary: Youtube Update Analytics Group
      description: 'Updates an existing analytics group. You can modify the group''s title

        and other editable properties. The group ID cannot be changed.'
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupCreateExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupIdPath'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupUpdateRequest'
            examples:
              GroupUpdateRequestExample:
                $ref: '#/components/examples/GroupUpdateRequestExample'
      responses:
        '200':
          description: Successfully updated analytics group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                SuccessfulGroupCreateExample:
                  $ref: '#/components/examples/SuccessfulGroupCreateExample'
        '400':
          description: Bad request - invalid update data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestErrorExample:
                  $ref: '#/components/examples/BadRequestErrorExample'
        '404':
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
    delete:
      tags:
      - Analytics > Groups
      operationId: deleteAnalyticsGroup
      summary: Youtube Delete Analytics Group
      description: 'Deletes an analytics group. This action is permanent and cannot be undone.

        All group items associated with the group will also be removed.'
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulDeleteExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupIdPath'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      responses:
        '204':
          description: Successfully deleted the analytics group
        '404':
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
components:
  examples:
    NotFoundErrorExample:
      summary: Not found error
      description: Example error response when resource is not found
      value:
        error:
          code: 404
          message: Resource not found
          errors:
          - domain: youtube.analytics
            reason: notFound
            message: The specified group was not found
            locationType: parameter
            location: groupId
    GroupCreateRequestExample:
      summary: Group creation request
      description: Example request body for creating a new analytics group
      value:
        snippet:
          title: My New Analytics Group
        contentDetails:
          itemType: youtube#video
    SuccessfulGroupCreateExample:
      summary: Successfully created group
      description: Example response for a newly created analytics group
      value:
        kind: youtube#group
        etag: newgroup123
        id: NEWgroup456789
        snippet:
          title: My New Analytics Group
          publishedAt: '2024-03-01T09:00:00Z'
        contentDetails:
          itemCount: 0
          itemType: youtube#video
    GroupUpdateRequestExample:
      summary: Group update request
      description: Example request body for updating an analytics group
      value:
        id: ABCdef123456
        snippet:
          title: Updated Analytics Group Name
    BadRequestErrorExample:
      summary: Bad request error
      description: Example error response for invalid parameters
      value:
        error:
          code: 400
          message: Invalid parameter value
          errors:
          - domain: youtube.analytics
            reason: invalidParameter
            message: The parameter 'startDate' has an invalid value
            locationType: parameter
            location: startDate
    UnauthorizedErrorExample:
      summary: Unauthorized error
      description: Example error response for authentication failure
      value:
        error:
          code: 401
          message: Invalid credentials
          errors:
          - domain: youtube.analytics
            reason: authError
            message: The access token is invalid or expired
            locationType: header
            location: Authorization
    SuccessfulGroupListExample:
      summary: Successful group list response
      description: Example response containing analytics groups
      value:
        kind: youtube#groupListResponse
        etag: abc123def456
        items:
        - kind: youtube#group
          etag: xyz789abc123
          id: ABCdef123456
          snippet:
            title: Top Performing Videos Q1 2024
            publishedAt: '2024-01-15T10:30:00Z'
          contentDetails:
            itemCount: 25
            itemType: youtube#video
        - kind: youtube#group
          etag: mno456pqr789
          id: GHIjkl789012
          snippet:
            title: Channel Performance Tracking
            publishedAt: '2024-02-01T14:00:00Z'
          contentDetails:
            itemCount: 5
            itemType: youtube#channel
  schemas:
    ErrorItem:
      type: object
      description: Individual error detail
      properties:
        domain:
          type: string
          description: Error domain
          example: youtube.analytics
        reason:
          type: string
          description: Error reason code
          example: invalidParameter
        message:
          type: string
          description: Detailed error message
          example: The parameter 'startDate' has an invalid value
        locationType:
          type: string
          description: Type of location where error occurred
          example: parameter
        location:
          type: string
          description: Specific location of the error
          example: startDate
    ErrorDetails:
      type: object
      description: Details about an API error
      required:
      - code
      - message
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable error message
          example: Invalid parameter value
        errors:
          type: array
          description: List of specific errors
          items:
            $ref: '#/components/schemas/ErrorItem'
    GroupUpdateRequest:
      type: object
      description: Request body for updating an analytics group
      required:
      - id
      - snippet
      properties:
        id:
          type: string
          description: The ID of the group to update
          example: ABCdef123456
        snippet:
          type: object
          required:
          - title
          properties:
            title:
              type: string
              description: The updated title for the group
              example: Updated Analytics Group Name
    GroupSnippet:
      type: object
      description: Basic information about an analytics group
      required:
      - title
      - publishedAt
      properties:
        title:
          type: string
          description: The title of the group
          example: Top Performing Videos Q1 2024
        publishedAt:
          type: string
          format: date-time
          description: When the group was created
          example: '2024-01-15T10:30:00Z'
    GroupCreateRequest:
      type: object
      description: Request body for creating a new analytics group
      required:
      - snippet
      - contentDetails
      properties:
        snippet:
          type: object
          required:
          - title
          properties:
            title:
              type: string
              description: The title for the new group
              example: My New Analytics Group
        contentDetails:
          type: object
          required:
          - itemType
          properties:
            itemType:
              type: string
              description: Type of items the group will contain
              enum:
              - youtube#channel
              - youtube#video
              example: youtube#video
    Group:
      type: object
      description: An analytics group for aggregating channel or video data
      required:
      - kind
      - id
      - snippet
      - contentDetails
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#group
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the group
          example: ABCdef123456
        snippet:
          $ref: '#/components/schemas/GroupSnippet'
        contentDetails:
          $ref: '#/components/schemas/GroupContentDetails'
    GroupContentDetails:
      type: object
      description: Content details for an analytics group
      required:
      - itemCount
      - itemType
      properties:
        itemCount:
          type: integer
          description: Number of items in the group
          example: 25
        itemType:
          type: string
          description: Type of items in the group
          enum:
          - youtube#channel
          - youtube#video
          example: youtube#video
    ErrorResponse:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    GroupListResponse:
      type: object
      description: Response containing a list of analytics groups
      required:
      - kind
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#groupListResponse
        etag:
          type: string
          description: ETag for caching purposes
        items:
          type: array
          description: List of analytics groups
          items:
            $ref: '#/components/schemas/Group'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results
  parameters:
    GroupId:
      name: id
      in: query
      required: false
      description: The unique identifier of an analytics group to retrieve
      schema:
        type: string
        example: ABCdef123456
    PrettyPrint:
      name: prettyPrint
      in: query
      required: false
      description: Returns response with indentations and line breaks for readability
      schema:
        type: boolean
        default: true
    GroupIdPath:
      name: groupId
      in: path
      required: true
      description: The unique identifier of the analytics group
      schema:
        type: string
        example: ABCdef123456
    PageToken:
      name: pageToken
      in: query
      required: false
      description: Token for retrieving the next page of results
      schema:
        type: string
    AccessToken:
      name: access_token
      in: query
      required: false
      description: OAuth 2.0 access token for authentication
      schema:
        type: string
    OnBehalfOfContentOwner:
      name: onBehalfOfContentOwner
      in: query
      required: false
      description: 'The content owner ID for YouTube content owner operations.

        Required for content owner authenticated requests.

        '
      schema:
        type: string
        example: ContentOwnerXYZ
  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