Subscriptions

  • A YouTube subscription notifies users about new videos or actions on a channel, such as uploads, ratings, or comments.

  • The API supports methods to list, insert, and delete subscription resources, allowing for management of user subscriptions.

  • Subscription resources contain details like the subscription's title, the channel subscribed to, creation time, and thumbnail images.

  • Content details in a subscription resource include the total item count, new item count, and the type of activity the subscription covers.

  • The subscription resource contains information about the subscriber, such as title, description, and thumbnails.

A subscription resource contains information about a YouTube user subscription. A subscription notifies a user when new videos are added to a channel or when another user takes one of several actions on YouTube, such as uploading a video, rating a video, or commenting on a video.

Methods

The API supports the following methods for subscriptions resources:

list
Returns subscription resources that match the API request criteria. Try it now.
insert
Adds a subscription for the authenticated user's channel. Try it now.
delete
Deletes a subscription. Try it now.

Resource representation

The following JSON structure shows the format of a subscriptions resource:

{
  "kind": "youtube#subscription",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelTitle": string,
    "title": string,
    "description": string,
    "resourceId": {
      "kind": string,
      "channelId": string,
    },
    "channelId": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    }
  },
  "contentDetails": {
    "totalItemCount": unsigned integer,
    "newItemCount": unsigned integer,
    "activityType": string
  },
  "subscriberSnippet": {
    "title": string,
    "description": string,
    "channelId": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    }
  }
}

Properties

The following table defines the properties that appear in this resource:

Properties
kind string
Identifies the API resource's type. The value will be youtube#subscription.
etag etag
The Etag of this resource.
id string
The ID that YouTube uses to uniquely identify the subscription.
snippet object
The snippet object contains basic details about the subscription, including its title and the channel that the user subscribed to.
snippet.publishedAt datetime
The date and time that the subscription was created. The value is specified in ISO 8601 format.
snippet.title string
The subscription's title.
snippet.description string
The subscription's details.
snippet.resourceId object
The id object contains information about the channel that the user subscribed to.
snippet.resourceId.kind string
The type of the API resource.
snippet.resourceId.channelId string
The value that YouTube uses to uniquely identify the channel that the user subscribed to.
snippet.channelId string
The ID that YouTube uses to uniquely identify the subscriber's channel. The resource_id object identifies the channel that the user subscribed to.
snippet.thumbnails object
A map of thumbnail images associated with the subscription. For each object in the map, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail.
snippet.thumbnails.(key) object
Valid key values are:
  • default – The default thumbnail image for this resource. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
  • medium – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
  • high – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall.
snippet.thumbnails.(key).url string
The image's URL.
snippet.thumbnails.(key).width unsigned integer
The image's width.
snippet.thumbnails.(key).height unsigned integer
The image's height.
contentDetails object
The contentDetails object contains basic statistics about the subscription.
contentDetails.totalItemCount unsigned integer
The approximate number of items that the subscription points to.
contentDetails.newItemCount unsigned integer
The number of new items in the subscription since its content was last read.
contentDetails.activityType string
The type of activity this subscription is for (only uploads, everything).

Valid values for this property are:
  • all
  • uploads
subscriberSnippet object
The subscriberSnippet object contains basic details about the subscriber.
subscriberSnippet.title string
The title of the subscriber's channel.
subscriberSnippet.description string
The description of the subscriber's channel.
subscriberSnippet.channelId string
The ID that YouTube assigns to uniquely identify the subscriber's channel.
subscriberSnippet.thumbnails object
Thumbnail images for the subscriber's channel.
subscriberSnippet.thumbnails.(key) object
Valid key values are:
  • default – The default thumbnail image for this resource. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
  • medium – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
  • high – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall.
subscriberSnippet.thumbnails.(key).url string
The image's URL.
subscriberSnippet.thumbnails.(key).width unsigned integer
The image's width.
subscriberSnippet.thumbnails.(key).height unsigned integer
The image's height.