Youtube Playlists API

openapi: 3.1.0
info:
  title: YouTube Analytics Analytics Groups Playlists 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: Playlists
  description: Operations related to YouTube playlist resources
paths:
  /playlists:
    get:
      operationId: youtube.playlists.list
      summary: Youtube List Playlists
      description: Returns a collection of playlists that match the API request parameters. You can retrieve playlists by ID, by channel, or for the authenticated user.
      tags:
      - Playlists
      parameters:
      - $ref: '#/components/parameters/part'
      - name: id
        in: query
        description: Comma-separated list of YouTube playlist IDs for the resources being retrieved.
        schema:
          type: string
        example: abc123def456
      - name: channelId
        in: query
        description: Indicates that the API response should only contain resources created by the channel.
        schema:
          type: string
        example: '500123'
      - name: mine
        in: query
        description: Set this parameter to true to instruct the API to return playlists owned by the authenticated user.
        schema:
          type: boolean
        example: true
      - $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 playlist resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistListResponse'
              examples:
                YoutubePlaylistsList200Example:
                  summary: Default youtube.playlists.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'
                        channelId: '500123'
                        title: Example Title
                        description: A sample description for this resource.
                        thumbnails: example_value
                        channelTitle: example_value
                        tags: {}
                        defaultLanguage: en
                      status:
                        privacyStatus: private
                      contentDetails:
                        itemCount: 42
        '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.playlists.insert
      summary: Youtube Create a Playlist
      description: Creates a playlist on behalf of the authenticated user. The user must be authorized to create playlists.
      tags:
      - Playlists
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The playlist resource to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Playlist'
            examples:
              YoutubePlaylistsInsertRequestExample:
                summary: Default youtube.playlists.insert request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    publishedAt: '2026-01-15T10:30:00Z'
                    channelId: '500123'
                    title: Example Title
                    description: A sample description for this resource.
                    thumbnails: example_value
                    channelTitle: example_value
                    tags:
                    - example_value
                    defaultLanguage: en
                  status:
                    privacyStatus: private
                  contentDetails:
                    itemCount: 42
      responses:
        '200':
          description: Successful response containing the newly created playlist resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
              examples:
                YoutubePlaylistsInsert200Example:
                  summary: Default youtube.playlists.insert 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      publishedAt: '2026-01-15T10:30:00Z'
                      channelId: '500123'
                      title: Example Title
                      description: A sample description for this resource.
                      thumbnails: example_value
                      channelTitle: example_value
                      tags:
                      - example_value
                      defaultLanguage: en
                    status:
                      privacyStatus: private
                    contentDetails:
                      itemCount: 42
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: youtube.playlists.update
      summary: Youtube Update a Playlist
      description: Modifies a playlist. The authenticated user must own the playlist being updated. Use the part parameter to specify the properties being updated.
      tags:
      - Playlists
      parameters:
      - $ref: '#/components/parameters/part'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      requestBody:
        description: The playlist resource with updated properties.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Playlist'
            examples:
              YoutubePlaylistsUpdateRequestExample:
                summary: Default youtube.playlists.update request
                x-microcks-default: true
                value:
                  kind: youtube#video
                  etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                  id: abc123def456
                  snippet:
                    publishedAt: '2026-01-15T10:30:00Z'
                    channelId: '500123'
                    title: Example Title
                    description: A sample description for this resource.
                    thumbnails: example_value
                    channelTitle: example_value
                    tags:
                    - example_value
                    defaultLanguage: en
                  status:
                    privacyStatus: private
                  contentDetails:
                    itemCount: 42
      responses:
        '200':
          description: Successful response containing the updated playlist resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
              examples:
                YoutubePlaylistsUpdate200Example:
                  summary: Default youtube.playlists.update 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    id: abc123def456
                    snippet:
                      publishedAt: '2026-01-15T10:30:00Z'
                      channelId: '500123'
                      title: Example Title
                      description: A sample description for this resource.
                      thumbnails: example_value
                      channelTitle: example_value
                      tags:
                      - example_value
                      defaultLanguage: en
                    status:
                      privacyStatus: private
                    contentDetails:
                      itemCount: 42
        '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.playlists.delete
      summary: Youtube Delete a Playlist
      description: Deletes a playlist. The authenticated user must own the playlist or be authorized to delete it.
      tags:
      - Playlists
      parameters:
      - name: id
        in: query
        required: true
        description: The ID of the playlist to delete.
        schema:
          type: string
        example: abc123def456
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          description: The playlist 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
  /playlists/{playlistId}:
    put:
      tags:
      - Playlists
      operationId: updatePlaylist
      summary: Youtube Update Playlist
      description: 'Updates a playlist''s metadata. This operation requires OAuth 2.0 authentication.

        You can only update playlists that belong to the authenticated user''s channel.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulPlaylistInsertExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/PlaylistIdPath'
      - $ref: '#/components/parameters/Part'
      - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaylistUpdateRequest'
            examples:
              PlaylistUpdateRequestExample:
                $ref: '#/components/examples/PlaylistUpdateRequestExample'
      responses:
        '200':
          description: Successfully updated playlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist_2'
              examples:
                SuccessfulPlaylistInsertExample:
                  $ref: '#/components/examples/SuccessfulPlaylistInsertExample'
        '404':
          description: Playlist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
    delete:
      tags:
      - Playlists
      operationId: deletePlaylist
      summary: Youtube Delete Playlist
      description: 'Deletes a playlist. This operation requires OAuth 2.0 authentication.

        You can only delete playlists that belong to the authenticated user''s channel.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulDeleteExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/PlaylistIdPath'
      - $ref: '#/components/parameters/AccessToken'
      responses:
        '204':
          description: Successfully deleted playlist
        '404':
          description: Playlist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
components:
  schemas:
    Playlist_2:
      type: object
      description: A YouTube playlist resource
      required:
      - kind
      - etag
      - id
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#playlist
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the playlist
          example: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
        snippet:
          $ref: '#/components/schemas/PlaylistSnippet'
        contentDetails:
          $ref: '#/components/schemas/PlaylistContentDetails'
        status:
          $ref: '#/components/schemas/PlaylistStatus'
    PlaylistUpdateRequest:
      type: object
      description: Request body for updating a playlist
      required:
      - id
      - snippet
      properties:
        id:
          type: string
          description: ID of the playlist to update
          example: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
        snippet:
          type: object
          required:
          - title
          properties:
            title:
              type: string
              description: Updated title
              example: Updated Playlist Name
            description:
              type: string
              description: Updated description
    ThumbnailDetails:
      type: object
      description: Thumbnail images at various resolutions
      properties:
        default:
          $ref: '#/components/schemas/Thumbnail'
        medium:
          $ref: '#/components/schemas/Thumbnail'
        high:
          $ref: '#/components/schemas/Thumbnail'
        standard:
          $ref: '#/components/schemas/Thumbnail'
        maxres:
          $ref: '#/components/schemas/Thumbnail'
    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'
    PlaylistSnippet:
      type: object
      description: Basic information about the playlist
      properties:
        publishedAt:
          type: string
          format: date-time
          description: When the playlist was created
          example: '2024-01-15T10:30:00Z'
        channelId:
          type: string
          description: ID of the channel that owns the playlist
          example: UC_x5XG1OV2P6uZZ5FSM9Ttw
        title:
          type: string
          description: Title of the playlist
          example: API Development Tutorials
        description:
          type: string
          description: Description of the playlist
          example: A collection of tutorials for API development...
        thumbnails:
          $ref: '#/components/schemas/ThumbnailDetails'
        channelTitle:
          type: string
          description: Title of the channel
          example: Google Developers
    PlaylistStatus:
      type: object
      description: Status information for the playlist
      properties:
        privacyStatus:
          type: string
          description: Privacy status of the playlist
          enum:
          - private
          - public
          - unlisted
          example: public
    PlaylistListResponse:
      type: object
      description: A list of playlist resources matching the request criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#playlistListResponse.
          default: youtube#playlistListResponse
          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 playlists that match the request criteria.
          items:
            $ref: '#/components/schemas/Playlist'
          example: []
    Thumbnail:
      type: object
      description: A thumbnail image
      properties:
        url:
          type: string
          description: URL of the thumbnail image
          example: https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg
        width:
          type: integer
          description: Width of the thumbnail
          example: 120
        height:
          type: integer
          description: Height of the thumbnail
          example: 90
    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
    Playlist:
      type: object
      description: A playlist resource represents a YouTube playlist.
      required:
      - kind
      - etag
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#playlist.
          default: youtube#playlist
          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 playlist.
          example: abc123def456
        snippet:
          type: object
          description: Basic details about the playlist such as its title, description, and thumbnails.
          properties:
            publishedAt:
              type: string
              format: date-time
              description: The date and time that the playlist was created.
            channelId:
              type: string
              description: The ID of the channel that published the playlist.
            title:
              type: string
              description: The playlist title.
            description:
              type: string
              description: The playlist description.
            thumbnails:
              type: object
              description: A map of thumbnail images associated with the playlist.
            channelTitle:
              type: string
              description: The channel title of the channel that the video belongs to.
            tags:
              type: array
              description: Keyword tags associated with the playlist.
              items:
                type: string
            defaultLanguage:
              type: string
              description: The language of the text in the playlist resource's snippet.title and snippet.description properties.
          example: example_value
        status:
          type: object
          description: The status object contains status information for the playlist.
          properties:
            privacyStatus:
              type: string
              description: The playlist's privacy status.
              enum:
              - private
              - public
              - unlisted
          example: example_value
        contentDetails:
          type: object
          description: The contentDetails object contains information about the playlist content.
          properties:
            itemCount:
              type: integer
              description: The number of videos in the playlist.
          example: example_value
    PlaylistContentDetails:
      type: object
      description: Content details for the playlist
      properties:
        itemCount:
          type: integer
          description: Number of videos in the playlist
          example: 25
  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
    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
    PlaylistIdPath:
      name: playlistId
      in: path
      required: true
      description: The unique identifier of the playlist
      schema:
        type: string
        example: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
    Part:
      name: part
      in: query
      required: true
      description: 'The part parameter specifies a comma-separated list of one or more

        resource properties that the API response will include.

        '
      schema:
        type: string
        example: snippet,contentDetails,statistics
    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'
    Unauthorized:
      description: The request was not authenticated or the credentials are invalid.
      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'
  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
    SuccessfulPlaylistInsertExample:
      summary: Successfully created playlist
      description: Example response for a newly created playlist
      value:
        kind: youtube#playlist
        etag: newplaylist123
        id: NEWplaylist456
        snippet:
          publishedAt: '2024-03-20T14:00:00Z'
          channelId: UC_x5XG1OV2P6uZZ5FSM9Ttw
          title: My New Playlist
          description: A collection of my favorite videos
          thumbnails:
            default:
              url: https://i.ytimg.com/vi/default.jpg
              width: 120
              height: 90
          channelTitle: My Channel
        contentDetails:
          itemCount: 0
        status:
          privacyStatus: public
    PlaylistUpdateRequestExample:
      summary: Playlist update request
      description: Example request body for updating a playlist
      value:
        id: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
        snippet:
          title: Updated Playlist Name
          description: Updated description
  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