Youtube Groups API

openapi: 3.2.0
info:
  title: YouTube Analytics Groups API
  description: The YouTube Analytics API lets you generate custom reports containing YouTube Analytics data for channels and content owners. Reports can be filtered by various dimensions such as date, country, and video, and measured by metrics including views, likes, estimated watch time, and revenue. The API also supports creating and managing groups and group items for organizing analytics data.
  version: v2
  contact:
    name: YouTube API Support
    url: https://developers.google.com/youtube/analytics
  termsOfService: https://developers.google.com/youtube/terms/api-services-terms-of-service
servers:
- url: https://youtubeanalytics.googleapis.com/v2
  description: YouTube Analytics API v2 base server
security:
- oauth2:
  - https://www.googleapis.com/auth/youtube
  - https://www.googleapis.com/auth/yt-analytics.readonly
tags:
- name: Groups
  description: Operations for managing YouTube Analytics groups
paths:
  /groups:
    get:
      operationId: youtubeAnalytics.groups.list
      summary: Youtube List Groups
      description: Returns a collection of groups that match the API request parameters. You can retrieve all groups that the authenticated user owns, or retrieve one or more groups by their unique IDs.
      tags:
      - Groups
      parameters:
      - name: id
        in: query
        description: Comma-separated list of YouTube group IDs for the resources being retrieved. If this parameter is not specified, the API will return all groups owned by the authenticated user.
        schema:
          type: string
        example: abc123def456
      - name: mine
        in: query
        description: Set this parameter to true to retrieve all groups owned by the authenticated user.
        schema:
          type: boolean
        example: true
      - name: pageToken
        in: query
        description: Identifies a specific page in the result set that should be returned. If specified, the API response should contain only that page.
        schema:
          type: string
        example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
      - name: onBehalfOfContentOwner
        in: query
        description: The onBehalfOfContentOwner parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successful response containing a list of group resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListResponse'
              examples:
                YoutubeanalyticsGroupsList200Example:
                  summary: Default youtubeAnalytics.groups.list 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    items:
                    - kind: youtube#video
                      etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                      id: abc123def456
                      snippet:
                        publishedAt: '2026-01-15T10:30:00Z'
                        title: Example Title
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: youtubeAnalytics.groups.insert
      summary: Youtube Create a Group
      description: Creates an Analytics group. The authenticated user must be authorized to create groups. A group must have at least one item before you can run a report for the group.
      tags:
      - Groups
      parameters:
      - name: onBehalfOfContentOwner
        in: query
        description: The onBehalfOfContentOwner parameter indicates that the request's authorization credentials identify a YouTube CMS user.
        schema:
          type: string
        example: example_value
      requestBody:
        description: The group resource to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
            examples:
              YoutubeanalyticsGroupsInsertRequestExample:
                summary: Default youtubeAnalytics.groups.insert request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    publishedAt: '2026-01-15T10:30:00Z'
                    title: Example Title
                  contentDetails:
                    itemCount: 42
                    itemType: youtube#channel
      responses:
        '200':
          description: Successful response containing the newly created group resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                YoutubeanalyticsGroupsInsert200Example:
                  summary: Default youtubeAnalytics.groups.insert 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      publishedAt: '2026-01-15T10:30:00Z'
                      title: Example Title
                    contentDetails:
                      itemCount: 42
                      itemType: youtube#channel
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: youtubeAnalytics.groups.update
      summary: Youtube Update a Group
      description: Modifies a group. The authenticated user must own the group being updated. Currently, the only property that can be updated is the group's title.
      tags:
      - Groups
      parameters:
      - name: onBehalfOfContentOwner
        in: query
        description: The onBehalfOfContentOwner parameter indicates that the request's authorization credentials identify a YouTube CMS user.
        schema:
          type: string
        example: example_value
      requestBody:
        description: The group resource with updated properties.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
            examples:
              YoutubeanalyticsGroupsUpdateRequestExample:
                summary: Default youtubeAnalytics.groups.update request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    publishedAt: '2026-01-15T10:30:00Z'
                    title: Example Title
                  contentDetails:
                    itemCount: 42
                    itemType: youtube#channel
      responses:
        '200':
          description: Successful response containing the updated group resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                YoutubeanalyticsGroupsUpdate200Example:
                  summary: Default youtubeAnalytics.groups.update 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      publishedAt: '2026-01-15T10:30:00Z'
                      title: Example Title
                    contentDetails:
                      itemCount: 42
                      itemType: youtube#channel
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: youtubeAnalytics.groups.delete
      summary: Youtube Delete a Group
      description: Deletes a group. The authenticated user must own the group being deleted. Deleting a group does not delete any of the resources contained in the group.
      tags:
      - Groups
      parameters:
      - name: id
        in: query
        required: true
        description: The id parameter specifies the YouTube group ID for the group being deleted.
        schema:
          type: string
        example: abc123def456
      - name: onBehalfOfContentOwner
        in: query
        description: The onBehalfOfContentOwner parameter indicates that the request's authorization credentials identify a YouTube CMS user.
        schema:
          type: string
        example: example_value
      responses:
        '204':
          description: The group was successfully deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The specified resource was not found.
      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'
    Unauthorized:
      description: The request was not authenticated or the credentials are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
    GroupListResponse:
      type: object
      description: A list of group resources matching the request criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#groupListResponse.
          default: youtube#groupListResponse
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        nextPageToken:
          type: string
          description: The token for the next page of results in the result set.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        items:
          type: array
          description: A list of groups that match the request criteria.
          items:
            $ref: '#/components/schemas/Group'
          example: []
    GroupContentDetails:
      type: object
      description: Describes the content of a YouTube Analytics group in terms of the number of items it contains and the type of items it contains.
      properties:
        itemCount:
          type: integer
          format: int64
          description: The number of items in the group.
          example: 42
        itemType:
          type: string
          description: The type of resources contained in the group. Valid values are youtube#channel, youtube#playlist, youtube#video, and youtubePartner#asset.
          enum:
          - youtube#channel
          - youtube#playlist
          - youtube#video
          - youtubePartner#asset
          example: youtube#channel
    Group:
      type: object
      description: A group resource represents a YouTube Analytics group, which is a custom collection of up to 500 channels, videos, playlists, or assets. You can use groups to simplify retrieving data for multiple resources.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#group.
          default: youtube#group
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        id:
          type: string
          description: The ID that YouTube uses to uniquely identify the group.
          example: abc123def456
        snippet:
          type: object
          description: The snippet object contains basic details about the group.
          properties:
            publishedAt:
              type: string
              format: date-time
              description: The date and time that the group was created.
            title:
              type: string
              description: The group title. The value must be a non-empty string.
          example: example_value
        contentDetails:
          $ref: '#/components/schemas/GroupContentDetails'
  securitySchemes:
    oauth2:
      type: oauth2
      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 for your YouTube content
            https://www.googleapis.com/auth/yt-analytics-monetary.readonly: View monetary and non-monetary YouTube Analytics reports for your YouTube content