# List the comments on a YouTube video

Returns a YouTube video's top-level comments, with author, likes and reply count. Use it to read how an audience reacts to a video.

Tool `youtube.video.comments` on YouTube. Contract version 1, released 2026-10-27.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/youtube.video.comments/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"video_id":"dQw4w9WgXcQ"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/youtube.video.comments/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"video_id": "dQw4w9WgXcQ"}},
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/youtube.video.comments/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"video_id": "dQw4w9WgXcQ"}}),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "youtube.video.comments",
    "input": {
      "video_id": "dQw4w9WgXcQ"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `video_id` | string | Yes |  | YouTube's identifier of the video, the 11 characters after watch?v= in its address. Matches `^[0-9A-Za-z_-]{11}$`. |
| `sort` | string | No | `relevance` | Order of the comments: relevance (YouTube's top comments) or newest. One of `relevance`, `newest`. |
| `next_page_token` | string | No |  | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same video_id and sort. |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### comments

A list of rows. Always present, possibly empty. The video's top-level comments; replies are not included.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | YouTube's identifier of the comment. |
| `text` | string | No | What the comment says. |
| `published_at` | string | No | When the comment was posted, in ISO 8601. |
| `author_id` | string | No | YouTube's identifier of the author's channel, which begins with UC. |
| `author_username` | string | No | The author's handle, without the @. |
| `author_name` | string | No | The author's display name. |
| `author_image_url` | string | No | Address of the author's profile picture. |
| `author_verified` | boolean | No | Whether YouTube marks the author as verified. |
| `like_count` | integer | No |  |
| `reply_count` | integer | No |  |
| `approx_like_count` | integer | No | Number of likes, approximate, rounded by the source (273K is 273000). |
| `approx_reply_count` | integer | No | Number of replies, approximate, rounded by the source (1.2K is 1200). |

### pagination

One object. Can be `null`. How to fetch the next page. Null on the last page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `next_page_token` | string | Yes | Send as next_page_token to fetch the next page. |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "comments": [
    {
      "id": "UgzKYksqeQ5gA3t0g0F4AaABAg",
      "text": "I Rick rolled my entire French class because we had to study a city in France and make a quiz about it as well as a presentation, I decided to make a Kahoot quiz because it’s very easy. I put a link in to this saying it’s the kahoot link. The teacher needless to say got very very mad. As well as my classmates asking who rick rolls in 2019",
      "published_at": null,
      "author_id": "UCKrzgYonJnMd0Dk7zQXjYXw",
      "author_username": null,
      "author_name": null,
      "author_image_url": "https://yt3.ggpht.com/ytc/AIdro_kDD-FhIbth2qcBbI9VGxR41dJa0kE3kN9iVlGzNgRU_g=s88-c-k-c0x00ffffff-no-rj",
      "author_verified": false,
      "like_count": null,
      "reply_count": null,
      "approx_like_count": 106000,
      "approx_reply_count": 645
    },
    {
      "id": "UgwPwTibxdgqCHZxktd4AaABAg",
      "text": "My algebra teacher said that this was a link to the test answers",
      "published_at": null,
      "author_id": "UCdi6tGxvFvTRGe-7dAn7m7w",
      "author_username": null,
      "author_name": null,
      "author_image_url": "https://yt3.ggpht.com/ytc/AIdro_kcDoQJUNDkDzTrA5kaF5ADVujN-6UcDjMP2Kydtw=s88-c-k-c0x00ffffff-no-rj",
      "author_verified": false,
      "like_count": null,
      "reply_count": null,
      "approx_like_count": 70000,
      "approx_reply_count": 647
    },
    {
      "id": "UgyyEqaBXOKgoi4cf7l4AaABAg",
      "text": "Ok let’s be honest here\nRick rolling is the one meme that will never die",
      "published_at": null,
      "author_id": "UCNRtoaGfHCLksAz2ofEAfgA",
      "author_username": null,
      "author_name": null,
      "author_image_url": "https://yt3.ggpht.com/ytc/AIdro_nyhrpC59MDbvwlTlkeHmG6xvzXfJQdI4SBR7r8a5XLhJg=s88-c-k-c0x00ffffff-no-rj",
      "author_verified": false,
      "like_count": null,
      "reply_count": null,
      "approx_like_count": 427000,
      "approx_reply_count": 746
    }
  ],
  "pagination": {
    "next_page_token": "pt1.dGlraHViOkVnMFNDMlJSZHpSM09WZG5XR05SR0FZeWxRTUsyQUpuWlhSZmNtRnVhMlZrWDNOMGNtVmhiWE10TFVOeFkwSkRTVUZGUmxKbE16QlVaMkZ1UVVWTGJIZEZTVEpHT0ZGblFWRlpRbmxMVFVGV2RqaEthalkxZDBkV1NsUTNhakJ5V25NeWEwTjNiRU5xU0U5SlpGbHhiWGg0YUhwbmJ6bFFRV3BrUlUxWlgxOWlWSFpMYlRoZmVuVjNVSGN5WW5KSFJYZFJSRFJXVGtaT2VIaFJjR0pvTUVJMmVVVkpOSE54ZFUxUFVWRnhTRzlQVnpJelIwTk1OMlJ2UVU5MVREUk5SM0ZGVmxKQmFFZEJNSEJaUkVSeFFrMVRaMnRIVDA1RldYVlFVRVZEVlZsVmFtTkZSVWw0UzI5VVVIZE1OMnMxZWtKNlkyRmxaamgwTkRWMU5XWXdVamRzVVRkdVMyTkVObTlCUlVKUlUwSlJhVWhKUW1kQlJXZFZTWEZEUVZsQlFrbEdRMGxuWjBkQlFWTkNkMmxLU1VKQlFrZEJRVk5DVVdsSFNVSm5RVVZuVlVsM1EwRlpRVUpKU0VOSlZXZEZRVlZaUVZKSlJrTk1jMmRIUVVGVFFuZHBSVWxDUVZCSFFVWlJRVVpuUWlJUklndGtVWGMwZHpsWFoxaGpVVEFBZUFFb0ZEQUJRaUZsYm1kaFoyVnRaVzUwTFhCaGJtVnNMV052YlcxbGJuUnpMWE5sWTNScGIyNCUzRA"
  }
}
```