# FlashData YouTube Channel API

Retrieve a YouTube channel profile and its recent videos by handle, including subscriber counts, channel images and video details.

Canonical reference: https://flashdata.dev/docs/sources/youtube_channel
Reviewed: 2026-10-23

Endpoint: POST https://data.flashdata.dev/v1/queries/realtime
Authentication: X-API-Key: YOUR_API_KEY
Modes: [Realtime](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/docs/reference/batch-and-bulk/reference.md#batch)

Required source permission: youtube_channel

Replace YOUR_API_KEY with an API key that has this source permission and available credits. Run requests on your server or agent host.

[Set up authentication](https://flashdata.dev/docs/guides/headers-and-authentication/reference.md)

[Work with a channel and its recent videos](https://flashdata.dev/docs/guides/youtube-data-guide/reference.md#channel)

<a id="quickstart"></a>

## Send a request

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_channel",
    "handle": "@jawed",
    "params": {
        "video_limit": 10,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_channel",
  "handle": "@jawed",
  "params": {
    "video_limit": 10
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parameters

<a id="parameters-group-0"></a>

### Request body

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Yes | — | Set to youtube_channel.  |
| <a id="parameter-handle"></a> handle | string | Yes | Not set | Channel handle, such as @jawed. The @ prefix is optional. Min length: 1. Max length: 100. |
| <a id="parameter-params"></a> params | object | No | {} | Settings for this request.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | No | Not set | Async and batch only. Public HTTPS completion URL on port 443, up to 2,048 characters. No user credentials or URL fragment. Omit, use null or an empty string for no notification. In a batch, set this on each query, outside params.  |

<a id="parameters-group-1"></a>

### Video selection

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-video_limit"></a> params.video_limit | integer | No | 20 | Maximum videos to include. Fewer may be available. Minimum: 1. Maximum: 100. |

<a id="response"></a>

## Read the result

Save the successful JSON response as response.json. Save this as read-response.py and run python read-response.py. It uses only Python's standard library and makes no new request.

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {
    "channelId": result.get("channelId"),
    "name": result.get("name"),
    "videos": [
        {"videoId": item.get("videoId"), "title": item.get("title")}
        for item in result.get("videos", [])
    ],
}
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Sample response

Recorded example; fields and counts depend on the source and requested input.
```json
{
  "source": "youtube_channel",
  "status": "done",
  "results": [
    {
      "channelId": "UC4QobU6STFB0P71PMvOGN5A",
      "channelHandle": "@jawed",
      "name": "jawed",
      "description": "",
      "subscriberCount": 6580000,
      "videoCount": 1,
      "viewCount": null,
      "avatarUrl": "https://yt3.googleusercontent.com/uI3VE4PVqvCy0xnWLqMJnEzyBUm3T8VHOCp4ee-1RxdHqKXCdUE_qXYQnpf9AfuEoIPactVyDhM=s0",
      "bannerUrl": null,
      "channelUrl": "https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A",
      "videos": [
        {
          "videoId": "jNQXAC9IVRw",
          "title": "Me at the zoo",
          "duration": 19,
          "viewCount": 431000000,
          "uploadDate": null,
          "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=-oaymwE2COADEI4CSFXyq4qpAygIARUAAIhCGAFwAcABBvABAfgBvgKAAvABigIMCAAQARhVIFkoZTAP&rs=AOn4CLDkGJrAGBspJ5G6u9b7tutsHbloEg"
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:41:47.218Z"
}
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| source | string | The requested API source. |
| status | string | done when the realtime request succeeds. |
| created_at | string | Response creation time in ISO 8601 format. |
| usage.credits | number | Credits charged for the request, based on your plan. |
| results[0].channelId | string | Channel ID. |
| results[0].channelHandle | string | Channel handle. |
| results[0].name | string | Channel name. |
| results[0].description | string | Channel description. |
| results[0].subscriberCount | number · nullable | Subscriber count. |
| results[0].videoCount | number · nullable | Total channel video count. |
| results[0].viewCount | number · nullable | Channel view count when available. |
| results[0].avatarUrl | string · nullable | Channel avatar URL. |
| results[0].bannerUrl | string · nullable | Channel banner URL. |
| results[0].channelUrl | string | Channel page URL. |
| results[0].videos | array | Recent videos, up to video_limit entries. |
| results[0].videos[].videoId | string | Video ID. |
| results[0].videos[].title | string | Video title. |
| results[0].videos[].duration | number · nullable | Duration in seconds. |
| results[0].videos[].viewCount | number · nullable | View count. |
| results[0].videos[].uploadDate | string · nullable | Upload date. |
| results[0].videos[].thumbnail | string · nullable | Video thumbnail URL. |

- Channel statistics and images may be unavailable. videoCount describes the channel; the videos array contains only the requested recent videos.

## Response formats

Responses use JSON by default. Choose another format with these optional headers.

- Accept: application/json (default) or text/plain. Plain text presents the same fields in a readable, indented layout.
- X-Respond-With: markdown. Leave unset for original fields. Markdown works with either response format.

Markdown is available for realtime queries and completed results.

The fields below describe the default JSON response.

[Request and response format examples](https://flashdata.dev/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## API basics

The request builder and examples above use this source's parameters. Use the Python and cURL examples below for shared submission, status and result steps. A Batch body is a JSON object containing queries; each item returns its own job ID.

- [Async request and receipt](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Check job status](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Retrieve completed results](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON requests](https://flashdata.dev/docs/reference/batch-and-bulk/reference.md#batch)
- [Customer OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Completion notifications

- [Receive and verify completion webhooks](https://flashdata.dev/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Troubleshooting

- [Errors and status codes](https://flashdata.dev/docs/errors/reference.md#status-codes)
- [When to retry](https://flashdata.dev/docs/errors/reference.md#retries)

## Related APIs

- [YouTube Video Metadata API](https://flashdata.dev/docs/sources/youtube_metadata/reference.md)
- [YouTube Search API](https://flashdata.dev/docs/sources/youtube_search/reference.md)
