# List a YouTube channel's videos

Returns a YouTube channel's videos, with view, like and comment counts, and the channel's profile. Use it to follow a channel's content.

Tool `youtube.channel.videos` 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.channel.videos/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"channel_id":"UCX6OQ3DkcsbYNE6H8uQQuVA"}}'
```

Python:

```python
import os

import httpx

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

TypeScript:

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

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "youtube.channel.videos",
    "input": {
      "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA"
    }
  }
}
```

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 |
| --- | --- | --- | --- | --- |
| `channel_id` | string | Yes |  | YouTube's identifier of the channel, which begins with UC, as in https://www.youtube.com/channel/ followed by it. Matches `^UC[0-9A-Za-z_-]{22}$`. |
| `next_page_token` | string | No |  | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same channel_id. |

## Output

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

### channel

One object. Can be `null`. The channel the videos belong to.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | YouTube's identifier of the channel, which begins with UC. |
| `username` | string | No | The channel's handle, without the @. The channel is at https://www.youtube.com/@ followed by it. |
| `name` | string | No | The channel's name. |
| `url` | string | No | Address of the channel on youtube.com. |
| `bio` | string | No | The channel's description. |
| `image_url` | string | No | Address of the channel's profile picture. |
| `verified` | boolean | No | Whether YouTube marks the channel as verified. |
| `follower_count` | integer | No | Number of subscribers. |
| `video_count` | integer | No | Number of public videos the channel published. |

### videos

A list of rows. Always present, possibly empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | YouTube's identifier of the video. The video is at https://www.youtube.com/watch?v= followed by it. |
| `url` | string | No | Address of the video on youtube.com. |
| `title` | string | No |  |
| `description` | string | No | The video's description. |
| `published_at` | string | No | When the video was published, in ISO 8601. |
| `duration_ms` | integer | No | Length of the video, in milliseconds. |
| `preview_image_url` | string | No | Address of the video's thumbnail. |
| `live` | boolean | No | Whether the video is a live stream on air now. |
| `view_count` | integer | No | Number of times the video was watched. |
| `approx_view_count` | integer | No | Number of times the video was watched, approximate, rounded by the source (24M is 24000000). |
| `like_count` | integer | No |  |
| `comment_count` | integer | No |  |

### 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
{
  "channel": {
    "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
    "username": null,
    "name": "MrBeast",
    "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
    "bio": "SUBSCRIBE FOR A COOKIE!\nNew MrBeast or MrBeast Gaming video every single Saturday at noon eastern time!\nAccomplishments:\n- Raised $20,000,000 To Plant 20,000,000 Trees\n- Removed 30,000,000 pounds of trash from the ocean\n- Helped 2,000 people walk again\n- Helped 1,000 blind people see\n- Helped 1,000 deaf people hear\n- Built wells in Africa\n- Built and gave away 100 houses\n- Adopted every dog in a shelter (twice)\n- Given millions to charity\n- Started my own snack company Feastables\n- Started my own software company Viewstats\n- Gave away a private island (twice)\n- Gave away 1 million meals\n- I counted to 100k\n- Ran a marathon in the world's largest shoes\n- Survived 50 hours in Antarctica\n- Recreated Squid Game in real life\n- Created the largest competition show with 1000 people (Beast Games)\n- Gave $5,000,000 to one person\n- Raised $40,000,000 To Bring Clean Water To Millions Of People\n- Granted 100+ Dream Wishes for Kids Fighting Cancer\n- Gave Away Another $5,000,000 On Beast Games S2\n",
    "image_url": "https://yt3.googleusercontent.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s900-c-k-c0x00ffffff-no-rj",
    "verified": true,
    "follower_count": null,
    "video_count": null
  },
  "videos": [
    {
      "id": "RE3_PGwDwhw",
      "url": "https://www.youtube.com/watch?v=RE3_PGwDwhw",
      "title": "Lose 150 Lbs Together, Win $250,000",
      "description": null,
      "published_at": null,
      "duration_ms": 2597000,
      "preview_image_url": "https://i.ytimg.com/vi/RE3_PGwDwhw/hq720_custom_2.jpg?sqp=CJzyhdcG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBNuf6hvm2hkJu5hnd1ClTGFZtOUA",
      "live": false,
      "view_count": null,
      "approx_view_count": 160000000,
      "like_count": null,
      "comment_count": null
    },
    {
      "id": "plN7JMbadRg",
      "url": "https://www.youtube.com/watch?v=plN7JMbadRg",
      "title": "Eat Everything In A Grocery Store, Win $1,000,000",
      "description": null,
      "published_at": null,
      "duration_ms": 3479000,
      "preview_image_url": "https://i.ytimg.com/vi/plN7JMbadRg/hq720_custom_1.jpg?sqp=CJzyhdcG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLC6NFn5c94zgwm8433jxZgwTplLdg",
      "live": false,
      "view_count": null,
      "approx_view_count": 306000000,
      "like_count": null,
      "comment_count": null
    },
    {
      "id": "v9QtM6qnG50",
      "url": "https://www.youtube.com/watch?v=v9QtM6qnG50",
      "title": "I Built A City To Save Kids From Illegal Labor",
      "description": null,
      "published_at": null,
      "duration_ms": 1143000,
      "preview_image_url": "https://i.ytimg.com/vi/v9QtM6qnG50/hq720_custom_1.jpg?sqp=CJzyhdcG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLD57NPY5Xu3enGqEujoGjyUaoZL-w",
      "live": false,
      "view_count": null,
      "approx_view_count": 116000000,
      "like_count": null,
      "comment_count": null
    }
  ],
  "pagination": {
    "next_page_token": "pt1.dGlraHViOjRxbUZzZ0xkQ0JJWVZVTllOazlSTTBSclkzTmlXVTVGTmtnNGRWRlJkVlpCR3NBSU9HZGhia0pvY1d0Q2JuRm9RbXB4WlVKbmIydE9iVXBvVFdwYWFFMTZhM1JOUkVGM1RVTXdlVTFIVG1oTVYwa3dXbTFWZEZwRVVtMU9WRkV6V21wUk1FNUhSbXBGZGsxR1VWZGFlbFl5ZEhOT2JYQndaVmhPTVZOcmNHOU9hMWt6VTBkYVNsbFliR1prYmxaUVZFUmFiVll3VG14VGJYQklUVEZvVldKRE1XbFRWMHB5VjBjMU1WUkdRakpQVjAxMFZFVkdVV0l6YURSaGJYTXhWRVJTZUZWVlRtaFNNVUpRWVVod1JFNVdXazlQVm1oWFRWVmtTRlZJYkZwalNIQjZaR3BhYmxRd1NtdFRSbEpRWTBSR1Mxb3pVVFZOTUZGNFZGZE9ibHBXU25WbGJtUmFUbXBWZVZac09YcFRWVGg2VWpCV1YxWldiRE5WTUVreFVteGFkbFpZUm5oV1ZGWnRWVzVDZG1ORlZrTlVSVkpIWlVSc2JGWnFaRmxpVldod1RWZE9lbVZGV1hsYWExWkVURmRhY21Kc1NrbGhiVXBtVXpGd2NGWlZVa1ZsV0ZwUlQxVTVRMDVxU2xaVFZUbHpXVk14UjJReE9UTmFla0YzWWxabmVXVkhSa2RWYmtFeVZWWTRNVk5xV1RSak1sSlpZVWhTTTJOWFRrNVJiVko1WVRGb1VHUlZlRXhOTW5SVlpWUk9TR05xYUVwV1dFWXpXVEExUTJKVVpISlhibkIyV1ZSV2RGUXdSbEpoUld0MFVrZFJkMVo2Um14a2ExRjNVV3N4TWsxWWFFeGxSMDAwVm01T1YyVnRPVWhWUld3Mll6RktWRkZZVGxkV1JWSkpVbTVPZGxSdE5YQk9SVVpOVkdwck1sZEZiekZqYWtweVUyeENjMkZIU2pWWmJuQktWa1JLVlZWVlZuSlNNVUozVmpOd1JGcHNaRkZUTW14dll6RkNWVnBYWkhCa2EzQTFWRzFhYlZSV1ZYcFRWbXhWWkVkV2VtUlZiM2hXUmtKRVVtcEtiRnBYVmxaa1JHaG9VVE5HTkZvd09YQk5WVXBNVDFWNFVsTldVbWhPYkZKdFZta3hORmRGV2t4TmJsVXlZekJTYTJOSGREQlBXR2hVVkZkV1VsUXdOVkZqUmxKcVkxUkthbEZzVm05aFYyeFZZbGhzY0dGSE5YVlhSMng0VDFaQ1UwNUhWbE5UTWs1WFUyeG9jbGd3ZEhOWlZtaHdXbGhXVFZkdFpFTmhSamx0VmpBNWJWZEZPV0ZVYkRsWVdqSXhlR1F4WkdwWmFtaDZVMVpaZDJGdE1IZFVNVTQyVWxoYWRGTnVTbGhOVjA1elZXMDFiVlZJVGtWU1ZGWjJXa2haTkZNeU5VcFRSVTAwVjIxU1RsRldWbTVTYXpWMlQwVTFiVll5TVRaa1ZFbzJUa1YwVUZkSE1WbFNTRlpVVlZkR1RFMXRTbkJoTWpsclVXdEthRlZYY0ZGVVZFcFpWRVZHZDJSV1NuRlRhMHBYVTNwQ1dWbDZaRWRrUjJST1kydzVWRTlHU20xTlZteHpVMjFTYm1OWGJHaE5hMXB5VmtWV1dWZ3pVbVpaZWtwVlpVaFNjRTFzWkVWa2VURTJUbGhTVlZOV1duSmliVFZTVkhreFRVMXNTVEJsUlVwRFlqTnNhMUZ0WnpOWFdFSlVaVVZzVFdGR1dtNU1Wa1kyVjBSQ2Mxb3lNWFJWTWs1b1RVVlJkR013Y0hKT1YxWlhZekZTU2xsVVJsVlVXRXBzWld0a1NWTnJlSEJsUjA1cFVrVXhWMVJxUW5oTmJrNVdXV3hCTTFsV2JITmhNRnBDVTBkb2FGSlZkRFpqVkZabVVsUldhbUZzT1hCVGJFRjRWVlZ3ZEZwVldtRlJNV041VVRKNFMxbHJjSGxrYTBWWlFrRWxNMFFsTTBRJTNE"
  }
}
```