Youtube Subscriptions API

openapi: 3.1.0
info:
  title: YouTube Analytics Analytics Groups Subscriptions 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: Subscriptions
  description: Operations related to YouTube channel subscriptions
paths:
  /subscriptions:
    get:
      operationId: youtube.subscriptions.list
      summary: Youtube List Subscriptions
      description: Returns subscription resources that match the API request criteria. Retrieve subscriptions for the authenticated user, a specific channel, or by subscription IDs.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/part'
      - name: id
        in: query
        description: Comma-separated list of YouTube subscription IDs for the resources being retrieved.
        schema:
          type: string
        example: abc123def456
      - name: mine
        in: query
        description: Set this parameter to true to retrieve the subscriptions of the authenticated user.
        schema:
          type: boolean
        example: true
      - name: channelId
        in: query
        description: Retrieves subscriptions for the channel with the specified YouTube channel ID.
        schema:
          type: string
        example: '500123'
      - $ref: '#/components/parameters/maxResults'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: Successful response containing a list of subscription resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
              examples:
                YoutubeSubscriptionsList200Example:
                  summary: Default youtube.subscriptions.list 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    prevPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    pageInfo:
                      totalResults: 42
                      resultsPerPage: 10
                    items:
                    - kind: youtube#video
                      etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                      id: abc123def456
                      snippet:
                        publishedAt: '2026-01-15T10:30:00Z'
                        title: Example Title
                        description: A sample description for this resource.
                        resourceId: {}
                        channelId: '500123'
                        thumbnails: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: youtube.subscriptions.insert
      summary: Youtube Subscribe to a Channel
      description: Adds a subscription for the authenticated user. The authenticated user must be authorized to create subscriptions.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The subscription resource to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
            examples:
              YoutubeSubscriptionsInsertRequestExample:
                summary: Default youtube.subscriptions.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
                    description: A sample description for this resource.
                    resourceId:
                      kind: youtube#video
                      channelId: '500123'
                    channelId: '500123'
                    thumbnails: example_value
      responses:
        '200':
          description: Successful response containing the newly created subscription resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              examples:
                YoutubeSubscriptionsInsert200Example:
                  summary: Default youtube.subscriptions.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
                      description: A sample description for this resource.
                      resourceId:
                        kind: youtube#video
                        channelId: '500123'
                      channelId: '500123'
                      thumbnails: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: youtube.subscriptions.delete
      summary: Youtube Unsubscribe From a Channel
      description: Deletes a subscription. The authenticated user must own the subscription being deleted.
      tags:
      - Subscriptions
      parameters:
      - name: id
        in: query
        required: true
        description: The ID of the subscription to delete.
        schema:
          type: string
        example: abc123def456
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          description: The subscription 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
  /subscriptions/{subscriptionId}:
    delete:
      tags:
      - Subscriptions
      operationId: deleteSubscription
      summary: Youtube Unsubscribe from Channel
      description: 'Deletes a subscription. This operation requires OAuth 2.0 authentication.

        You can only delete subscriptions that belong to the authenticated user.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulDeleteExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdPath'
      - $ref: '#/components/parameters/AccessToken'
      responses:
        '204':
          description: Successfully deleted subscription
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
components:
  parameters:
    fields:
      name: fields
      in: query
      description: Selector specifying which fields to include in a partial response. Use this parameter to reduce bandwidth usage by selecting only the fields you need.
      schema:
        type: string
    SubscriptionIdPath:
      name: subscriptionId
      in: path
      required: true
      description: The unique identifier of the subscription
      schema:
        type: string
        example: SUBScription123abc
    AccessToken:
      name: access_token
      in: query
      required: false
      description: OAuth 2.0 access token for authentication
      schema:
        type: string
    pageToken:
      name: pageToken
      in: query
      description: Identifies a specific page in the result set that should be returned. In an API response, the nextPageToken and prevPageToken properties identify other pages available.
      schema:
        type: string
    part:
      name: part
      in: query
      required: true
      description: Specifies a comma-separated list of one or more resource properties that the API response will include. The part parameter value must include the id property.
      schema:
        type: string
    maxResults:
      name: maxResults
      in: query
      description: The maximum number of items that should be returned in the result set. Acceptable values are 0 to 50, inclusive.
      schema:
        type: integer
        minimum: 0
        maximum: 50
        default: 5
    key:
      name: key
      in: query
      description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
      schema:
        type: string
  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:
    PageInfo:
      type: object
      description: Paging details for a list operation, including information about the total number of resources and the number per page.
      properties:
        totalResults:
          type: integer
          description: The total number of results in the result set.
          example: 42
        resultsPerPage:
          type: integer
          description: The number of results included in the API response.
          example: 10
    ErrorResponse:
      type: object
      description: A standard error response returned by the YouTube Data 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.
            errors:
              type: array
              description: A list of individual errors.
              items:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                  domain:
                    type: string
                    description: The domain in which the error occurred.
                  reason:
                    type: string
                    description: The reason for the error.
          example: example_value
    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'
    ErrorResponse_2:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    SubscriptionListResponse:
      type: object
      description: A list of subscription resources matching the request criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#subscriptionListResponse.
          default: youtube#subscriptionListResponse
          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.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        prevPageToken:
          type: string
          description: The token for the previous page of results.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        items:
          type: array
          description: A list of subscriptions that match the request criteria.
          items:
            $ref: '#/components/schemas/Subscription'
          example: []
    ErrorItem:
      type: object
      description: Individual error detail
      properties:
        domain:
          type: string
          description: Error domain
          example: youtube.parameter
        reason:
          type: string
          description: Error reason code
          example: invalidParameter
        message:
          type: string
          description: Detailed error message
          example: The parameter 'part' is required
        locationType:
          type: string
          description: Type of location where error occurred
          example: parameter
        location:
          type: string
          description: Specific location of the error
          example: part
    Subscription:
      type: object
      description: A subscription resource contains information about a YouTube user's subscription to a channel.
      required:
      - kind
      - etag
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#subscription.
          default: youtube#subscription
          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 subscription.
          example: abc123def456
        snippet:
          type: object
          description: The snippet object contains basic details about the subscription.
          properties:
            publishedAt:
              type: string
              format: date-time
              description: The date and time that the subscription was created.
            title:
              type: string
              description: The subscription title.
            description:
              type: string
              description: The subscription description.
            resourceId:
              type: object
              description: The resourceId object contains information about the resource to which the subscriber subscribed.
              properties:
                kind:
                  type: string
                  description: The type of the API resource.
                channelId:
                  type: string
                  description: The value that YouTube uses to uniquely identify the channel that the user subscribed to.
            channelId:
              type: string
              description: The ID of the channel that the subscription belongs to.
            thumbnails:
              type: object
              description: A map of thumbnail images associated with the subscription.
          example: example_value
  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.video
            reason: videoNotFound
            message: The video identified by the parameter id could not be found
            locationType: parameter
            location: id
  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