---
title: List channel videos | Vid Kraken API
description: List recent videos for a YouTube channel.
url: https://vidkraken.com/docs/endpoint/list-channel-videos
updated: '2026-10-24'
---

# List channel videos

For AI agents: docs index at https://vidkraken.com/docs/llms.txt; any page as Markdown by adding .md to its URL.

`POST https://vidkraken.com/api/v2/list-channel`

List recent videos for a YouTube channel. Returns the raw
`yt-dlp --flat-playlist -J` output, including channel metadata
and an `entries` array with one item per video.

`maxVideos` controls how many videos are returned (1–1000,
default 5). Higher values take proportionally longer.

**Cost:** account add-on — not included in standard plans;
contact hello@vidkraken.com to enable it. Counts 1 unit per 10
items returned (rounded up). No bandwidth cost; failures are
not charged.

```bash
curl -X POST "https://vidkraken.com/api/v2/list-channel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channelUrl":"https://www.youtube.com/@RickAstleyYT"}'
```

## Authorization

Bearer token. API key issued from the dashboard, sent as `Authorization: Bearer YOUR_API_KEY`. Get a key at https://vidkraken.com/login.

## Request body

- `channelUrl` (string, required)

  YouTube channel URL (e.g. `https://www.youtube.com/@channelHandle`).

- `maxVideos` (integer)

  Maximum number of videos to return.

  Default: `5`.

### Examples

First 5 videos of a channel:

```json
{
  "channelUrl": "https://www.youtube.com/@RickAstleyYT"
}
```

First 25 videos:

```json
{
  "channelUrl": "https://www.youtube.com/@RickAstleyYT",
  "maxVideos": 25
}
```

## Responses

### 200

Raw yt-dlp channel listing. The exact field set depends on
yt-dlp's output for the given channel — most callers care
about `entries[]`, where each entry is a video summary.

- `id` (string)

- `title` (string)

- `channel` (string)

- `channel_id` (string)

- `channel_url` (string)

- `entries` (array of object)

  Flat list of videos. Items are yt-dlp's flat-playlist video summaries.

```json
{
  "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "title": "Rick Astley - Videos",
  "channel": "Rick Astley",
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "channel_url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
  "entries": [
    {
      "id": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "duration": 213,
      "view_count": 1700000000,
      "uploader": "Rick Astley"
    }
  ]
}
```

### 400

Invalid input — missing or malformed field.

Body: `ApiError`.

missing-url:

```json
{
  "error": "Missing required field: url",
  "code": "INVALID_REQUEST"
}
```

bad-format:

```json
{
  "error": "Invalid format. Must be one of: 1080, 720, 480, 360, audio",
  "code": "INVALID_REQUEST"
}
```

live-in-progress:

```json
{
  "error": "Live on-going videos are not supported. Try again after the live stream ends.",
  "code": "INVALID_REQUEST"
}
```

too-long:

```json
{
  "error": "This video is too long to download in audio-aac (21,812 hours, about 1,265 GB; the limit is 100 GB per file).",
  "code": "INVALID_REQUEST"
}
```

### 401

Missing or invalid API key.

Body: `ApiError`.

missing:

```json
{
  "error": "Missing API key. Provide it as 'Bearer YOUR_API_KEY'",
  "code": "UNAUTHORIZED"
}
```

invalid:

```json
{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}
```

### 403

Usage limit reached for the current plan — the bandwidth
allowance (plus any overage allowance) or a request quota is
exhausted. Upgrade or wait for the next billing cycle. The
error string is `Credit limit reached` for backwards
compatibility.

Body: `ApiError`.

```json
{
  "error": "Credit limit reached",
  "code": "LIMIT_REACHED"
}
```

### 500

Unexpected server error.

Body: `ApiError`.

```json
{
  "error": "Failed to enqueue download job",
  "code": "INTERNAL_ERROR"
}
```

## Schemas

### `ApiError`

- `error` (string, required)

  Human-readable error message.

- `code` (string, required)

  Machine-readable error code; branch on this rather than on
  `error`. New codes may be added, so treat an unknown one by
  its HTTP status. See the table under Errors in the API
  description for what each one means.

  One of: `INVALID_REQUEST`, `UNAUTHORIZED`, `LIMIT_REACHED`, `NOT_FOUND`, `VIDEO_NOT_FOUND`, `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`, `TOO_MANY_PENDING`, `INTERNAL_ERROR`, `UNAVAILABLE`.

- `details` (string)

  Optional extra context — e.g. yt-dlp's error message on `500`s.

Full API reference, including the download.finished webhook: https://vidkraken.com/docs.md · OpenAPI: https://vidkraken.com/openapi.json