Skip to main content

Fetch a video's comments

Fetch the comments on a video, optionally including replies.

GET /v1/youtube/video/{video_id}/comments

Path parameter​

ParameterDescription
video_idThe 11-character video id, e.g. dQw4w9WgXcQ. See identifiers.

Query parameters​

ParameterTypeDefaultDescription
sortstringtopComment order: top or newest (the full, unfiltered set).
include_repliesbooleanfalseInclude replies to comments in the results.
max_resultsinteger100Maximum number of comments to return. Range 1–500.
Getting the full set

The default top view is filtered by YouTube. Use sort=newest to retrieve the complete, unfiltered comment stream.

Example​

curl -G "$LISTENX_BASE/v1/youtube/video/abc123XYZ01/comments" \
-H "X-API-Key: $LISTENX_KEY" \
--data-urlencode 'sort=newest' \
--data-urlencode 'include_replies=true' \
--data-urlencode 'max_results=100'

Response​

{
"video": "abc123XYZ01",
"sort": "newest",
"include_replies": true,
"requested": 100,
"returned": 100,
"results": [
{
"comment_id": "UgxR1…",
"text": "Range figures finally match real-world driving.",
"author": "@evdriver",
"author_channel_id": "UC000000000000000000777",
"published": "2 days ago",
"like_count": 42,
"like_count_text": "42",
"reply_count": 3,
"is_reply": false,
"heart": true
}
],
"billing": {
"endpoint": "youtube.comments",
"units": 5,
"unit_price": "0.010000",
"amount": "0.050000",
"balance_after": "19.950000",
"request_id": "…"
}
}

Fields​

FieldDescription
videoThe video id the comments were fetched for.
sortThe comment order used.
include_repliesWhether replies were included.
requestedThe max_results you asked for.
returnedNumber of comments in results.
results[]Comment records.

Comment record​

FieldDescription
comment_idComment id.
textComment text.
author / author_channel_idAuthor display name and channel id.
publishedRelative publish time, e.g. 2 days ago.
like_count / like_count_textLike count and its display string.
reply_countNumber of replies.
is_replytrue if this is a reply to another comment.
hearttrue if hearted by the creator.

Billing​

Billed per block of results returned (a block is up to 20 comments), minimum 1 unit. So max_results=100 costs up to 5 units (fewer if the video has fewer comments). See Billing.

Errors​

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