Fetch a video's comments
Fetch the comments on a video, optionally including replies.
GET /v1/youtube/video/{video_id}/comments
Path parameter
| Parameter | Description |
|---|---|
video_id | The 11-character video id, e.g. dQw4w9WgXcQ. See identifiers. |
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
sort | string | top | Comment order: top or newest (the full, unfiltered set). |
include_replies | boolean | false | Include replies to comments in the results. |
max_results | integer | 100 | Maximum 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
| Field | Description |
|---|---|
video | The video id the comments were fetched for. |
sort | The comment order used. |
include_replies | Whether replies were included. |
requested | The max_results you asked for. |
returned | Number of comments in results. |
results[] | Comment records. |
Comment record
| Field | Description |
|---|---|
comment_id | Comment id. |
text | Comment text. |
author / author_channel_id | Author display name and channel id. |
published | Relative publish time, e.g. 2 days ago. |
like_count / like_count_text | Like count and its display string. |
reply_count | Number of replies. |
is_reply | true if this is a reply to another comment. |
heart | true 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
| HTTP | code | Meaning |
|---|---|---|
| 404 | not_found | The video is private, removed, or does not exist. |
| 429 | upstream_rate_limited | Transient upstream block — retry with backoff. |