Skip to main content
SocialAPI reads the comments on the videos of a connected YouTube channel and acts on them: reply, post a top-level comment, hide, hold for review, ban the author, edit your own comments, and delete your own comments. YouTube comments use the same endpoints as every other platform, plus 2 YouTube endpoints for moderation and editing. The cross-platform rules are in Comments. A reply or a top-level comment costs 1 interaction credit, and each channel can post 5 of them per day (midnight to midnight Pacific Time) through the reply endpoint and the social_api_reply_to_comment MCP tool. Reading, hiding, moderating, editing, and deleting cost no credits. YouTube sends no comment events, so read new comments with the list endpoints.

Endpoints

{post_id} is the YouTube video ID, for example dQw4w9WgXcQ: the id of a video in GET /v1/inbox/comments, or targets[].platform_post_id on a video you published through SocialAPI. {comment_id} accepts the comment’s sapi_cmt_ ID or YouTube’s comment ID (platform_id). See IDs.

Your first request

List the comments on a video, most relevant first. account_id is required:
Response (HTTP 200):
Use id as {comment_id} in the other comment calls. To answer Jane, send the reply request in Reply or post a top-level comment.

List videos with comments

GET /v1/inbox/comments?account_id={account_id} lists the channel’s videos, newest published first, with the same parameters, fields, and pagination as on every platform: see List posts with comments. The id of each video is its YouTube video ID. On a YouTube video, comment_count can differ from the count YouTube shows, and can trail new comments. Pass the channel’s account_id when you poll: without it, the counts on YouTube videos can stay out of date.

List comments on a video

GET /v1/inbox/comments/{post_id} returns the top-level comments on 1 video. Replies are listed separately: see Replies. A moderation_status or order outside these lists, or a q longer than 256 bytes, returns 400 validation.field_invalid. A comment you hide with the hide endpoint stays in the default list with is_hidden: true. The held_for_review and likely_spam filters do not return it, and no filter lists rejected comments only. A page can hold fewer comments than limit. Follow next_cursor until has_more is false: see Pagination. The fields are the same as on every platform (List comments and replies). On YouTube: When the video has comments turned off, the call returns 422 platform.youtube.comments_disabled. Retrying does not help: stop requesting that video until the channel owner turns comments back on in YouTube Studio. After that, the error can continue for up to 24 hours.

Replies

YouTube threads are 1 level deep. Every reply belongs to a top-level comment, and a reply has no replies of its own. GET /v1/inbox/comments/{post_id}/{comment_id}/replies lists the replies to the top-level comment {comment_id}, in the same shape as comments. It takes account_id (required), limit (default 10, a value above 100 is treated as 100), and cursor. It ignores moderation_status, order, and q.
Each reply’s parent_id is the platform_id of its top-level comment. To answer a reply, reply to its top-level comment: pass the reply’s parent_id as comment_id.

Reply or post a top-level comment

POST /v1/inbox/comments/{post_id} posts as the channel. With comment_id, it replies to that top-level comment. Without comment_id, it posts a new top-level comment on the video.
Response (HTTP 200):
comment_id in the response is the new comment’s sapi_cmt_ ID. Each call costs 1 interaction credit. When the plan’s interaction allowance is used up, the call returns 429 validation.interaction_limit_exhausted. The credit comes back when the call fails with a validation.* error: see When a credit comes back. Each connected channel can post 5 replies and top-level comments per day, through POST /v1/inbox/comments/{post_id} and the MCP tool social_api_reply_to_comment combined. Comments posted in YouTube itself, and a post’s first_comment, do not count. The day runs from midnight to midnight Pacific Time. A 6th call returns 429 validation.youtube_daily_reply_limit and costs no credit: wait for midnight Pacific Time. A comment that YouTube refuses does not count toward the 5. Edits do not count. GET /v1/accounts/{account_id}/limits returns daily_replies_limit and daily_replies_remaining for the channel: see Read a platform’s remaining quota.

Hide and unhide a comment

POST /v1/inbox/comments/{post_id}/{comment_id}/hide sets the comment to rejected, which removes it from public view. Rejecting a top-level comment also hides all of its replies. Hiding is free.
Response (HTTP 200):
DELETE on the same path, with account_id as a query parameter, unhides a comment. Unhide works on a held_for_review comment. Do not use it on a rejected comment: YouTube does not move a rejected comment back to published, and a hidden comment is rejected. To keep a comment out of view while you decide, set it to held_for_review with the moderate endpoint instead of hiding it.

Moderate a comment

POST /v1/platforms/youtube/comments/{comment_id}/moderate sets a comment’s moderation status explicitly, and can ban its author from commenting on your channel. Moderating is free. YouTube accepts it only from the owner of the channel or video the comment is on.
Response (HTTP 200):
A missing account_id or post_id returns 400 validation.field_required. An account on another platform returns 501 resource.not_supported. {comment_id} accepts the sapi_cmt_ ID or YouTube’s comment ID.

Edit your own comment

PATCH /v1/platforms/youtube/comments/{comment_id} replaces the text of a comment your channel wrote. Editing is free and does not count toward the daily limit of 5.
Response (HTTP 200):
account_id, post_id (the YouTube video ID), and text are all required. A missing one returns 400 validation.field_required. YouTube refuses an edit to a comment another person wrote. An account on another platform returns 501 resource.not_supported.

Delete a comment

DELETE /v1/inbox/comments/{post_id}/{comment_id}?account_id={account_id} deletes a comment your channel wrote. It returns { "success": true }, costs no credit, and cannot be undone. capabilities.can_delete is true on every YouTube comment, including other people’s. Deleting a comment your channel did not write returns 422 platform.youtube.processing_failure. Hide it instead.

What YouTube does not allow

  • Like or unlike a comment. YouTube has no comment-like API. The call returns 501 resource.not_supported.
  • Private reply to a commenter. YouTube has no private replies or DMs. The call returns 501 resource.not_supported.
  • Delete another person’s comment. YouTube deletes only comments your channel wrote. Hide the comment instead.
  • Edit another person’s comment. YouTube refuses it.
  • List only rejected comments. No moderation_status value does it.
  • Restore a hidden (rejected) comment to published. YouTube does not allow it. Use held_for_review for comments you plan to restore.
  • Reply to a reply. Threads are 1 level deep. Reply to the top-level comment.
  • Comments on Community posts. YouTube has no API for them. Only video comments are listed.

Limits

Errors and debugging

Check these in order when a YouTube comment call fails or returns nothing:
  1. 401, 403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks the scope in Scopes.
  2. 404 account.not_found, 403 account.reconnection_required, 401 platform.youtube.auth, 401 platform.youtube.unauthorized. The acc_ ID is not yours, or the account needs reconnecting. After 401 platform.youtube.unauthorized, a healthy account keeps working: reconnect only if it persists.
  3. 403 platform.youtube.account_suspended. YouTube suspended or closed the account or its channel. Reconnecting does not help: see Suspended or closed channels.
  4. 403 account.permission_missing. The account lacks the permission the call needs: comments.read to list comments and replies, comments.write to reply, hide, unhide, moderate, edit, or delete. error.meta.permission names it.
  5. 400 validation.body_invalid, 400 validation.field_required, 400 validation.field_invalid. The JSON body is malformed, a required field is missing, or a parameter has a wrong value. For the last 2 codes, error.meta.field names the field.
  6. 400 validation.id_invalid, 400 validation.id_platform_mismatch. The comment ID is the wrong type or belongs to another platform: see IDs. The moderate and edit endpoints do not return these codes.
  7. 404 resource.not_found. The video or the comment does not exist on YouTube: it was deleted, or the ID is wrong.
  8. 422 platform.youtube.comments_disabled. The video has comments turned off. Stop requesting it until the owner turns them back on.
  9. 422 platform.youtube.processing_failure. YouTube refused the request. On delete, your channel did not write the comment: hide it instead. On hide or moderate, the commenter already deleted the comment, or YouTube could not process the request: retry once, and stop if it repeats. On a reply or an edit, check the text and the comment ID, then retry once.
  10. 403 platform.youtube.forbidden. YouTube refused the action for lack of permission, or the comment was deleted, or the comment ID is invalid. Check that the comment still exists and is on a video of the connected channel. Retrying does not help.
  11. 4xx platform.youtube.api_error. YouTube refused the request for another reason, for example replying to a comment whose parent is private, or an account YouTube does not allow to comment. error.message carries YouTube’s reason. Fix the request: retrying the same request fails again.
  12. 503 platform.youtube.api_error. YouTube failed or could not be reached. Retry with backoff. Before you retry a reply, list the comments to check whether it was posted.
  13. 403 platform.youtube.insufficientPermissions. The connection lacks the YouTube scope. Reconnect the account.
  14. 429 validation.youtube_daily_reply_limit. The channel posted its 5 replies and top-level comments for the day. Wait for midnight Pacific Time.
  15. 429 validation.interaction_limit_exhausted. Your plan’s interaction allowance for the billing period is used up. Retrying does not help: wait for the next billing period or upgrade your plan, see Plans and usage.
  16. 429 platform.youtube.rate_limit. YouTube’s own limit. Read Retry-After when it is present. Without it, back off as described in Rate limits.
  17. 501 resource.not_supported. YouTube lacks the action (like, private reply), or the moderate or edit endpoint received an account on another platform.
The full catalog is in Errors.

Scopes

The YouTube connection itself uses the 1 OAuth scope listed in YouTube scopes.

Events

YouTube sends no comment events, so SocialAPI emits no comment.received for YouTube. Read new comments with GET /v1/inbox/comments/{post_id}, and the replies to a comment with its replies endpoint. The post and account events a YouTube channel emits are in YouTube webhook events.

Use from an AI agent

No MCP tool sets held_for_review, bans an author, or edits a comment: use the REST endpoints for those. The tool list is in MCP tools.
Last modified on November 15, 2026