Returns a list of comment threads that match the API request parameters. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/data/getting-started.md.txt#quota) 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. | | `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](https://developers.google.com/youtube/data/guides/authentication.md.txt). 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 Don't 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. For more details, see the [error message](https://developers.google.com/youtube/data/reference/rest/v3/errors.md.txt) documentation. | 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 the `allThreadsRelatedToChannelId` parameter couldn't 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 couldn't be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response.