Comments API ​

The comments inbox collects comments that people leave on your published posts. You can list them, reply as the connected account, and mark them done. All routes are under /api/comments.

Auth is in the REST API overview.

Which comments endpoints can I call? ​

Which plans and platforms are supported? ​

The comments inbox is on the Team and Agency plans. On Free and Creator every route returns 403:

{
  "success": false,
  "error": "The comments inbox is not available on your current plan. Upgrade to Team or Agency to continue.",
  "statusCode": 403,
  "path": "/api/comments",
  "timestamp": "2026-11-14T09:00:00.000Z"
}

Supported platforms: YouTube, Bluesky, Reddit and Mastodon. The live list is in supportedPlatforms on every GET /comments response. Comments on other platforms are not collected.

Owners, admins and editors have both permissions. Contributors have comment.view only, so they can read but not reply. An API key acts with the workspace owner's role.

An API key with guardrails can call GET /comments only. Sync, reply and status changes return 403 for a guarded key. See API keys and guardrails.

What does a comment look like? ​

{
  "id": "6a1f0c2a9d3e4f5a6b7c8d01",
  "platform": "youtube",
  "connection": { "id": "6a04f715d3d7d93575e65d13", "slug": "youtube-mybrand", "name": "My Brand" },
  "post": { "id": "6b1f0c2a9d3e4f5a6b7c8d9e", "platformPostId": "dQw4w9WgXcQ" },
  "platformCommentId": "UgxKz3m2Qv8bT9",
  "parentId": null,
  "text": "Great video! Is there a follow-up coming?",
  "author": {
    "name": "Jane Doe",
    "handle": "janedoe",
    "avatarUrl": "https://yt3.ggpht.com/...",
    "profileUrl": "https://www.youtube.com/@janedoe"
  },
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&lc=UgxKz3m2Qv8bT9",
  "likeCount": 3,
  "isOwn": false,
  "status": "open",
  "postedAt": "2026-11-14T08:12:00.000Z",
  "repliedAt": null
}

How do I list comments? ​

GET /comments returns comments on your published posts, newest first. Your own replies are not included.

curl "https://api.socifyr.com/api/comments?status=open&platform=youtube&limit=10" \
  -H "Authorization: Bearer sk_..."

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "6a1f0c2a9d3e4f5a6b7c8d01",
        "platform": "youtube",
        "connection": { "id": "6a04f715d3d7d93575e65d13", "slug": "youtube-mybrand", "name": "My Brand" },
        "post": { "id": "6b1f0c2a9d3e4f5a6b7c8d9e", "platformPostId": "dQw4w9WgXcQ" },
        "platformCommentId": "UgxKz3m2Qv8bT9",
        "parentId": null,
        "text": "Great video! Is there a follow-up coming?",
        "author": { "name": "Jane Doe", "handle": "janedoe" },
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&lc=UgxKz3m2Qv8bT9",
        "likeCount": 3,
        "isOwn": false,
        "status": "open",
        "postedAt": "2026-11-14T08:12:00.000Z",
        "repliedAt": null
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10,
    "supportedPlatforms": ["youtube", "reddit", "bluesky", "mastodon"]
  }
}

The connection filter only matches active accounts. An unknown or disconnected connection returns 400 Connection "<ref>" not found. A postId that is not a valid ID returns 400.

How do I fetch new comments now? ​

Comments sync on their own every 30 minutes. POST /comments/sync queues a sync now and returns right away. It takes no body and is limited to 3 calls per minute.

The response is 202 Accepted with { "queued": true }. The sync runs in the background, so call GET /comments again after a short wait (or poll it) to see new comments. Only one sync per workspace runs at a time. A request while one is queued or running joins that sync.

curl -X POST "https://api.socifyr.com/api/comments/sync" \
  -H "Authorization: Bearer sk_..."

{ "success": true, "data": { "queued": true } }

A sync checks the 50 most recent posts published in the last 30 days on supported platforms. Posts on disconnected accounts are skipped.

Why do new YouTube comments take a while to appear? ​

YouTube comment sync runs on a daily API unit budget (YouTube's quota is shared with publishing). To stay inside it, a post is only re-fetched when its comment count changed, or on an age-based backoff: posts from the last 48 hours are checked on every sync, older ones at most every 12 hours. When the day's budget is spent, YouTube sync pauses until the next UTC day. New YouTube comments can therefore take a while to show up, even after POST /comments/sync.

How long are comments kept? ​

Comments older than 60 days are removed. A comment deleted on the platform disappears on the next full sync of its post. Disconnecting an account deletes the stored comments for that account, and deleting a workspace deletes all of its comments.

How do I reply to a comment? ​

POST /comments/:id/reply posts a reply on the platform as the connected account. The body has one field, text, from 1 to 5000 characters. Leading and trailing spaces are trimmed.

The reply must also fit the platform's own limit, for example 300 graphemes on Bluesky. On Mastodon the @mention of the comment's author that Socifyr adds counts toward the limit. A reply that is too long returns 400 Reply is too long for <platform>: N of M characters.

Only one reply per comment can be in flight. A second request while the first is still being sent returns 409. Sending the same text to the same comment twice within a minute returns the first reply instead of posting a duplicate.

curl -X POST "https://api.socifyr.com/api/comments/6a1f0c2a9d3e4f5a6b7c8d01/reply" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Thanks Jane! Part two is out next week." }'

The response is 201 with the reply that was posted. The original comment is marked done.

{
  "success": true,
  "data": {
    "id": "6a1f0c2a9d3e4f5a6b7c8d02",
    "platform": "youtube",
    "connection": { "id": "6a04f715d3d7d93575e65d13", "slug": "youtube-mybrand", "name": "My Brand" },
    "post": { "id": "6b1f0c2a9d3e4f5a6b7c8d9e", "platformPostId": "dQw4w9WgXcQ" },
    "platformCommentId": "UgxKz3m2Qv8bT9.9xYz",
    "parentId": "UgxKz3m2Qv8bT9",
    "text": "Thanks Jane! Part two is out next week.",
    "author": { "name": "My Brand", "handle": "mybrand" },
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&lc=UgxKz3m2Qv8bT9.9xYz",
    "likeCount": null,
    "isOwn": true,
    "status": "done",
    "postedAt": "2026-11-14T09:30:00.000Z",
    "repliedAt": null
  }
}

A reply is public as soon as it is posted. Socifyr cannot edit or delete it afterwards.

How do I mark a comment done or open? ​

PATCH /comments/:id sets status to open or done. Use done for comments that need no reply.

curl -X PATCH "https://api.socifyr.com/api/comments/6a1f0c2a9d3e4f5a6b7c8d01" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "done" }'

The response is the updated comment.

What errors can the comments endpoints return? ​

Frequently asked questions ​

Why don't I see comments from Instagram or Facebook? Only YouTube, Bluesky, Reddit and Mastodon are supported. Check supportedPlatforms for the current list.

Why is a comment missing? Comments are fetched every 30 minutes. Call POST /comments/sync to queue a sync now, then list comments again after a short wait. Only comments on posts published through Socifyr in the last 30 days are collected, from the 50 most recent posts. YouTube comments can take longer because their sync is budgeted. Comments older than 60 days are removed.

Are my replies listed? No. GET /comments leaves out your own replies. The reply is returned by POST /comments/:id/reply.

Next steps ​

• Comments in the TypeScript SDK
• socifyr comments in the CLI
• Comments inbox in the dashboard
• MCP comment tools