Skip to main content

Fetch a channel

Fetch a channel's reference data and metrics by its id or handle.

GET /v1/youtube/channel/{channel_id}

Path parameter​

ParameterDescription
channel_idA channel id (UC…) or a handle (@name). See identifiers.

Example​

curl "$LISTENX_BASE/v1/youtube/channel/@autoreview" \
-H "X-API-Key: $LISTENX_KEY"

Response​

{
"channel": {
"type": "channel",
"channel_id": "UC000000000000000000001",
"url": "https://www.youtube.com/channel/UC000000000000000000001",
"title": "Auto Review",
"description": "Independent electric-vehicle reviews and range tests.",
"handle": "@autoreview",
"subscribers": 1230000,
"subscribers_text": "1.23M subscribers",
"video_count": 842,
"video_count_text": "842 videos",
"view_count": 210400000,
"view_count_text": "210M views",
"thumbnail": "https://yt3.ggpht.com/…",
"banner": "https://yt3.ggpht.com/…",
"country": "US",
"joined_date": "Joined Mar 3, 2012",
"links": {
"Website": "https://autoreview.example",
"X": "https://x.com/autoreview"
}
},
"billing": {
"endpoint": "youtube.channel",
"units": 1,
"unit_price": "0.010000",
"amount": "0.010000",
"balance_after": "19.990000",
"request_id": "…"
}
}

Fields​

FieldDescription
channel_idThe channel id.
urlCanonical channel URL.
titleChannel name.
descriptionChannel description / about text.
handleChannel handle, e.g. @autoreview.
subscribers / subscribers_textSubscriber count (rounded by YouTube) and its display string.
video_count / video_count_textPublic video count.
view_count / view_count_textTotal channel views.
thumbnail / bannerChannel avatar and banner image URLs.
countryChannel country, when listed.
joined_dateChannel creation date, as shown on YouTube.
linksCreator-listed external links (label → URL).

Billing​

Billed per request — 1 unit per call. See Billing.

Errors​

HTTPcodeMeaning
404not_foundThe channel is private, removed, or does not exist.
429upstream_rate_limitedTransient upstream block — retry with backoff.