youtube/video/comments — the top-level thread, with nobody's name

The call

Parameters (1)

That list is the whole list, and anything else is ignored in silence. An undeclared parameter is not rejected — it produces no error, no warning and no filtering. Check a parameter against this table before assuming a narrower result came back.

What the parameter list does not tell you

⚠️ THERE ARE NO AUTHOR FIELDS, AND THE UPSTREAM HAD THEM. A real call on 4 October 2026 returned 100 comments. Checked field by field against the official Data API v3 response behind it: the upstream carried display name, channel id and avatar URL for every one of them, and we dropped all three before the response reached the client. This is OURS, not a limitation we inherited.

THE REASON IS A LINE WE DREW, AND IT IS NARROW. A comment is a published sentence; the person who wrote it did not publish a profile by writing it. Handing back a hundred names and avatars per call turns one question about a video into a roster of people who were not the subject of the query — the same reasoning that keeps the reply tree out of `bluesky/post`. The sentences are public and we serve them. The roster we do not assemble.

SO SOME THINGS ARE NOT POSSIBLE WITH THIS ROUTE, and that is the honest framing rather than a workaround to find. You cannot group comments by commenter, cannot count how often one account appears, and cannot follow a commenter to their channel. If your use case needs any of that, this route is the wrong source and will remain so — it is not an oversight that a future version fixes.

A HUNDRED IS THE UPSTREAM'S PAGE, not a cap of ours, and `limit` is not declared because the route does not read one. Replies are NOT included: a top-level comment with answers under it gives you the comment, and the answers come from `youtube/video/comment/replies`, one call per parent.

Measured caveats (2)

Why there is no success body on this page

The 200 body for this endpoint is not transcribed here. Reading it needs a client key, and there is no client key on the machine these pages were built from — internal keys exist only as hashes, by design. An example we never received would look exactly like one we did, so instead of composing one, the response shape is documented field by field on the schema pages below. Those are generated from the contract and tested against it in both directions; an invented example would be tested by nothing.

Response shapes (2)

• PostsEnvelope — Every posts endpoint answers with this envelope. Eight fields, all required: you can read `success` and `credits_used` without checking whether they came.
• ApiError — Every 4xx and 5xx from the API carries this object. The `error` value is a stable string you can branch on; the extra fields appear only for the errors that have something to report.

Error codes (8)

Every one of them carries the same body shape: ApiError. The error value is a stable string you can branch on — branch on that, never on the message text.

400 · 401 · 402 · 404 · 405 · 451 · 503 · 502

Machine-readable

This endpoint is in /openapi.json (OpenAPI 3.1), with its cost on the operation itself. If you are generating a client, use the spec rather than this page — and note that the spec is filtered by what is switched on right now, so it is the better answer to "can I call this today".