A commentThread resource contains information about a YouTube comment thread, which comprises a top-level comment and replies, if any exist, to that comment. A commentThread resource can represent comments about either a video or a channel.

Both the top-level comment and the replies are actually comment resources nested inside the commentThread resource. The commentThread resource does not necessarily contain all replies to a comment, and you need to use the comments.list method if you want to retrieve all replies for a particular comment. Also note that some comments do not have replies.


The API supports the following methods for commentThreads resources:

Returns a list of comment threads that match the API request parameters. Try it now.
Creates a new top-level comment. To add a reply to an existing comment, use the comments.insert method instead. Try it now.
Modifies the top-level comment in a comment thread. Try it now.

Resource representation

The JSON structure below shows the format of a commentThreads resource:

  "kind": "youtube#commentThread",
  "etag": etag,
  "id": string,
  "snippet": {
    "channelId": string,
    "videoId": string,
    "topLevelComment": comments Resource,
    "canReply": boolean,
    "totalReplyCount": unsigned integer,
    "isPublic": boolean
  "replies": {
    "comments": [
      comments Resource


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

kind string
Identifies the API resource's type. The value will be youtube#commentThread.
etag etag
The Etag of this resource.
id string
The ID that YouTube uses to uniquely identify the comment thread.
snippet object
The snippet object contains basic details about the comment thread. It also contains the thread's top-level comment, which is a comment resource.
snippet.channelId string
The YouTube channel that is associated with the comments in the thread. (The snippet.videoId property identifies the video.)
  • If the comments are about a video, then the value identifies the channel that uploaded the video. (The snippet.videoId property identifies the video.)
  • If the comments refer to the channel itself, the snippet.videoId property will not have a value.
snippet.videoId string
The ID of the video that the comments refer to, if any. If this property is not present or does not have a value, then the thread applies to the channel and not to a specific video.
snippet.topLevelComment object
The thread's top-level comment. The property's value is a comment resource.
snippet.canReply boolean
This setting indicates whether the current viewer can reply to the thread.
snippet.totalReplyCount unsigned integer
The total number of replies that have been submitted in response to the top-level comment.
snippet.isPublic boolean
This setting indicates whether the thread, including all of its comments and comment replies, is visible to all YouTube users.
replies object
The replies object is a container that contains a list of replies to the comment, if any exist. The replies.comments property represents the list of comments itself.
replies.comments[] list
A list of one or more replies to the top-level comment. Each item in the list is a comment resource.

The list contains a limited number of replies, and unless the number of items in the list equals the value of the snippet.totalReplyCount property, the list of replies is only a subset of the total number of replies available for the top-level comment. To retrieve all of the replies for the top-level comment, you need to call the comments.list method and use the parentId request parameter to identify the comment for which you want to retrieve replies.