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
`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.