List Comment Threads
youtube_list_comment_threadsRetrieve top-level comment threads for a YouTube video or channel. Filter by search terms, order by time or relevance, and paginate through results.
Instructions
Retrieves a page of top-level comment threads for a YouTube video or channel.
Args
videoId(string, optional) — ID of the video whose comment threads to list.channelId(string, optional) — Channel ID; lists all threads related to that channel (includes video comments and channel comments).Exactly one of
videoId/channelIdmust be supplied.order("time" | "relevance", default "time") — Sort order.searchTerms(string, optional) — Filter threads containing this text.maxResults(1–50, default 25) — Number of threads per page.pageToken(string, optional) — Cursor returned from a previous call to fetch the next page.response_format("markdown" | "json", default "markdown") — Output format.
Returns
{
"threads": [
{
"id": "string",
"authorDisplayName": "string",
"text": "string",
"likeCount": 0,
"publishedAt": "ISO-8601",
"updatedAt": "ISO-8601",
"totalReplyCount": 0,
"replies": [ { "id": "string", "authorDisplayName": "string", "text": "string" } ]
}
],
"nextPageToken": "string | null"
}Examples
List the first 10 comment threads on a video:
{ "videoId": "dQw4w9WgXcQ", "maxResults": 10 }Page through channel comments:
{ "channelId": "UCxxxxxxx", "pageToken": "CAUQAA" }
Errors
400 if neither or both of
videoId/channelIdare provided.403 if comments are disabled on the video or quota is exceeded.
404 if the video or channel does not exist.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| videoId | No | Video ID whose comment threads to list. Exactly one of videoId/channelId required. | |
| channelId | No | Channel ID; lists all threads related to the channel. Exactly one of videoId/channelId required. | |
| order | No | Sort order: "time" (newest first) or "relevance". | time |
| searchTerms | No | Optional text filter; only threads containing this string are returned. | |
| maxResults | No | Number of threads per page (1–50, default 25). | |
| pageToken | No | Pagination cursor from a previous response's nextPageToken. | |
| response_format | No | Output format: "markdown" (default) or "json". | markdown |