CommentThreads: list

Returns a list of comment threads that match the API request parameters.

Quota impact: A call to this method has a quota cost of 1 unit.

Common use cases

Request

HTTP request

GET https://www.googleapis.com/youtube/v3/commentThreads

Parameters

The following table lists the parameters that this query supports. All of the parameters listed are query parameters.

Parameters
Required parameters
`part`	`string` The `part` parameter specifies a comma-separated list of one or more `commentThread` resource properties that the API response will include. The following list contains the `part` names that you can include in the parameter value: `id` `replies` `snippet`
Filters (specify exactly one of the following parameters)
`allThreadsRelatedToChannelId`	`string` The `allThreadsRelatedToChannelId` parameter instructs the API to return all comment threads associated with the specified channel. The response can include comments about the channel or about the channel's videos.
`channelId`	`string` The `channelId` parameter instructs the API to return comment threads containing comments about the specified channel. (The response will not include comments left on videos that the channel uploaded.)
`id`	`string` The `id` parameter specifies a comma-separated list of comment thread IDs for the resources that should be retrieved.
`videoId`	`string` The `videoId` parameter instructs the API to return comment threads associated with the specified video ID.
Optional parameters
`maxResults`	`unsigned integer` The `maxResults` parameter specifies the maximum number of items that should be returned in the result set. Note: This parameter is not supported for use in conjunction with the `id` parameter. Acceptable values are `1` to `100`, inclusive. The default value is `20`.
`moderationStatus`	`string` This parameter can only be used in a properly authorized request. Set this parameter to limit the returned comment threads to a particular moderation state. Note: This parameter is not supported for use in conjunction with the `id` parameter. The default value is `published`. Acceptable values are: `heldForReview` – Retrieve comment threads that are awaiting review by a moderator. A comment thread can be included in the response if the top-level comment or at least one of the replies to that comment are awaiting review. `likelySpam` – Retrieve comment threads classified as likely to be spam. A comment thread can be included in the response if the top-level comment or at least one of the replies to that comment is considered likely to be spam. `published` – Retrieve threads of published comments. This is the default value. A comment thread can be included in the response if its top-level comment has been published.
`order`	`string` The `order` parameter specifies the order in which the API response should list comment threads. Valid values are: `time` - Comment threads are ordered by time. This is the default behavior. `relevance` - Comment threads are ordered by relevance. Note: This parameter is not supported for use in conjunction with the `id` parameter.
`pageToken`	`string` The `pageToken` parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` property identifies the next page of the result that can be retrieved. Note: This parameter is not supported for use in conjunction with the `id` parameter.
`searchTerms`	`string` The `searchTerms` parameter instructs the API to limit the API response to only contain comments that contain the specified search terms. Note: This parameter is not supported for use in conjunction with the `id` parameter.
`textFormat`	`string` Set this parameter's value to `html` or `plainText` to instruct the API to return the comments left by users in html formatted or in plain text. The default value is `html`. Acceptable values are: `html` – Returns the comments in HTML format. This is the default value. `plainText` – Returns the comments in plain text format.

Request body

Do not provide a request body when calling this method.

Response

If successful, this method returns a response body with the following structure:

{
  "kind": "youtube#commentThreadListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    commentThread Resource
  ]
}

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#commentThreadListResponse`.
`etag`	`etag` The Etag of this resource.
`nextPageToken`	`string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set.
`pageInfo`	`object` The `pageInfo` object encapsulates paging information for the result set.
`pageInfo.totalResults`	`integer` The total number of results in the result set.
`pageInfo.resultsPerPage`	`integer` The number of results included in the API response.
`items[]`	`list` A list of comment threads that match the request criteria.

Errors

The following table identifies error messages that the API could return in response to a call to this method. Please see the error message documentation for more detail.

Error type	Error detail	Description
`badRequest (400)`	`operationNotSupported`	The id filter is only compatible with comments based on Google+.
`badRequest (400)`	`processingFailure`	The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `commentThread` resource in the request body to ensure that it is valid.
`forbidden (403)`	`commentsDisabled`	The video identified by the `videoId` parameter has disabled comments.
`forbidden (403)`	`forbidden`	One or more of the requested comment threads cannot be retrieved due to insufficient permissions. The request might not be properly authorized.
`notFound (404)`	`channelNotFound`	The channel identified by either the `channelId` or the `allThreadsRelatedToChannelId` parameter could not be found.
`notFound (404)`	`commentThreadNotFound`	One or more of the specified comment threads cannot be found. Check the values of the request's `id` parameter to ensure that it is correct.
`notFound (404)`	`videoNotFound`	The video identified by the `videoId` parameter could not be found.

Try it!

Use the APIs Explorer to call this API and see the API request and response.