Subscriptions

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
kindstring
Identifies the API resource's type. The value will be youtube#subscription.
etagetag
The Etag of this resource.
idstring
The ID that YouTube uses to uniquely identify the subscription.
snippetobject
The snippet object contains basic details about the subscription, including its title and the channel that the user subscribed to.
snippet.publishedAtdatetime
The date and time that the subscription was created. The value is specified in ISO 8601 format.
snippet.titlestring
The subscription's title.
snippet.descriptionstring
The subscription's details.
snippet.resourceIdobject
The id object contains information about the channel that the user subscribed to.
snippet.resourceId.kindstring
The type of the API resource.
snippet.resourceId.channelIdstring
The value that YouTube uses to uniquely identify the channel that the user subscribed to.
snippet.channelIdstring
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.thumbnailsobject
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).urlstring
The image's URL.
snippet.thumbnails.(key).widthunsigned integer
The image's width.
snippet.thumbnails.(key).heightunsigned integer
The image's height.
contentDetailsobject
The contentDetails object contains basic statistics about the subscription.
contentDetails.totalItemCountunsigned integer
The approximate number of items that the subscription points to.
contentDetails.newItemCountunsigned integer
The number of new items in the subscription since its content was last read.
contentDetails.activityTypestring
The type of activity this subscription is for (only uploads, everything).

Valid values for this property are:
  • all
  • uploads
subscriberSnippetobject
The subscriberSnippet object contains basic details about the subscriber.
subscriberSnippet.titlestring
The title of the subscriber's channel.
subscriberSnippet.descriptionstring
The description of the subscriber's channel.
subscriberSnippet.channelIdstring
The ID that YouTube assigns to uniquely identify the subscriber's channel.
subscriberSnippet.thumbnailsobject
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).urlstring
The image's URL.
subscriberSnippet.thumbnails.(key).widthunsigned integer
The image's width.
subscriberSnippet.thumbnails.(key).heightunsigned integer
The image's height.