Comments and actions

A comment is one comment or reply on a connected Facebook, Instagram, TikTok, YouTube or Threads post or ad, with what CommentGate decided about it. Read them with every filter the inbox has, and act on them exactly like the inbox does.

Updated September 26, 2026

The comment object

Example

{
  "id": "2a8d5bac-3084-472a-92d9-700577412c23",
  "external_id": "918273645501928_484690767",
  "parent_external_id": null,
  "platform": "facebook",
  "surface": "ad",
  "status": "hidden",
  "text": "Congratulations! You were picked as our giveaway winner. DM me to claim",
  "has_media": false,
  "language": "en",
  "author": {
    "id": "10090124627",
    "name": "Giveaway Team",
    "handle": null
  },
  "account": {
    "id": "cf2d0cac-6c2e-4510-8d91-4ce6545d7202",
    "name": "Wildermere"
  },
  "post": {
    "external_id": "104829301847362_918273645501928",
    "permalink": "https://www.facebook.com/104829301847362_918273645501928"
  },
  "ad": {
    "id": "120210384756102938",
    "name": "Alder Trail Boot, fall launch, video 15s"
  },
  "reason": "scam 0.99",
  "decided_by": "rule",
  "scores": {
    "scam": 0.99,
    "spam": 0.94
  },
  "needs_reply": false,
  "created_at": "2026-09-22T18:22:30Z",
  "received_at": "2026-09-22T18:22:31.412000Z",
  "decided_at": "2026-09-22T18:22:33Z",
  "replied_at": null
}

platform is facebook, instagram, tiktok, youtube or threads. surface is organic (a post) or ad.
status is visible, hidden, deleted, review (waiting for a person) or pending (not decided yet). TikTok, YouTube and Threads comments are never deleted: those platforms only allow hiding other people's comments.
external_id and every platform id are strings. parent_external_id is set on replies.
scores holds classifier probabilities per category (0 to 1), or null when the comment was not classified. reason is the short reason shown in the inbox.
decided_by is rule, classifier or person.
created_at is when the person commented, received_at when CommentGate got it (with microseconds, the order lists use), decided_at when it was decided.

List comments

GET/api/v1/comments

Comments across every connected account, newest first by received_at. Every filter can be combined. An empty parameter (status=) counts as not set.

To sync incrementally, store the newest received_at you have seen and poll with since set to it. Please poll no more than once a minute, or subscribe to a REST hook instead.

Who can call it: Any API key.

Query parameters

status enum: review is waiting for a person, pending is not decided yet.
One of: visible, hidden, deleted, review, pending
platform enum: Only comments from this platform.
One of: facebook, instagram, tiktok, youtube, threads
surface enum: organic (a post) or ad.
One of: organic, ad
account_id string · up to 64 characters: A connected account's id (account.id).
ad_id string · up to 64 characters: The platform ad id (ad.id).
post_id string · up to 128 characters: The platform post id (post.external_id).
external_id string · up to 128 characters: The platform comment id, to find one comment by the id the platform gave it.
since datetime: Received at or after this time. ISO 8601 with an offset.
until datetime: Received before this time. ISO 8601 with an offset.
limit integer · 1 to 100 · default 50: How many to return per page.
cursor string · up to 200 characters: next_cursor from the previous page. Leave it out for the first page.

Example

Request

curl "https://commentgate.com/api/v1/comments?status=hidden&platform=instagram&surface=ad&limit=20" \
  -H "Authorization: Bearer $COMMENTGATE_API_KEY"

200 OK. A page of comments. next_cursor is null on the last page.

200 OK response

{
  "data": [
    {
      "id": "2a8d5bac-3084-472a-92d9-700577412c23",
      "external_id": "918273645501928_484690767",
      "parent_external_id": null,
      "platform": "facebook",
      "surface": "ad",
      "status": "hidden",
      "text": "Congratulations! You were picked as our giveaway winner. DM me to claim",
      "has_media": false,
      "language": "en",
      "author": {
        "id": "10090124627",
        "name": "Giveaway Team",
        "handle": null
      },
      "account": {
        "id": "cf2d0cac-6c2e-4510-8d91-4ce6545d7202",
        "name": "Wildermere"
      },
      "post": {
        "external_id": "104829301847362_918273645501928",
        "permalink": "https://www.facebook.com/104829301847362_918273645501928"
      },
      "ad": {
        "id": "120210384756102938",
        "name": "Alder Trail Boot, fall launch, video 15s"
      },
      "reason": "scam 0.99",
      "decided_by": "rule",
      "scores": {
        "scam": 0.99,
        "spam": 0.94
      },
      "needs_reply": false,
      "created_at": "2026-09-22T18:22:30Z",
      "received_at": "2026-09-22T18:22:31.412000Z",
      "decided_at": "2026-09-22T18:22:33Z",
      "replied_at": null
    }
  ],
  "next_cursor": "MjAyNi0wOS0yMlQxODoyMjozMS40MTIwMDBafDJhOGQ1YmFj"
}

Errors

HTTP	Code	When
400	`invalid_request`	A filter or the cursor is not valid
401	`unauthorized`	Missing, unknown or revoked key

Also as list_comments (MCP), commentgate comments list.

Get a comment

GET/api/v1/comments/:id

One comment with everything CommentGate knows about it.

Who can call it: Any API key.

Path parameters

id string· required: The CommentGate comment id (id on the comment object).

Example

Request

curl https://commentgate.com/api/v1/comments/2a8d5bac-3084-472a-92d9-700577412c23 \
  -H "Authorization: Bearer $COMMENTGATE_API_KEY"

200 OK. The comment.

200 OK response

{
  "data": {
    "id": "2a8d5bac-3084-472a-92d9-700577412c23",
    "external_id": "918273645501928_484690767",
    "parent_external_id": null,
    "platform": "facebook",
    "surface": "ad",
    "status": "hidden",
    "text": "Congratulations! You were picked as our giveaway winner. DM me to claim",
    "has_media": false,
    "language": "en",
    "author": {
      "id": "10090124627",
      "name": "Giveaway Team",
      "handle": null
    },
    "account": {
      "id": "cf2d0cac-6c2e-4510-8d91-4ce6545d7202",
      "name": "Wildermere"
    },
    "post": {
      "external_id": "104829301847362_918273645501928",
      "permalink": "https://www.facebook.com/104829301847362_918273645501928"
    },
    "ad": {
      "id": "120210384756102938",
      "name": "Alder Trail Boot, fall launch, video 15s"
    },
    "reason": "scam 0.99",
    "decided_by": "rule",
    "scores": {
      "scam": 0.99,
      "spam": 0.94
    },
    "needs_reply": false,
    "created_at": "2026-09-22T18:22:30Z",
    "received_at": "2026-09-22T18:22:31.412000Z",
    "decided_at": "2026-09-22T18:22:33Z",
    "replied_at": null
  }
}

Errors

HTTP	Code	When
401	`unauthorized`	Missing, unknown or revoked key
404	`not_found`	No comment with that id in this workspace

Also as get_comment (MCP), commentgate comments get.

Act on a comment

POST/api/v1/comments/:id/actions

Hide, reply, delete and the rest, exactly like the inbox: the action shows in the comment's history under the key's creator and follows the same platform rules. Platform actions run within seconds; read the comment again to see the confirmed status.

When the platform refuses later (for example, Instagram does not allow replies to a hidden comment), the comment keeps its previous status.

Who can call it: A key whose creator can moderate (owner, admin, manager or moderator). Runs as that person.

Path parameters

id string· required: The CommentGate comment id (id on the comment object).

Body

action enum· required: hide, unhide, allow (mark it fine, unhiding it if hidden), archive and unarchive (inbox only), restore (out of the Bin), delete and like (Facebook and Instagram), block and unblock (the author, Facebook only), or reply.
One of: hide, unhide, allow, archive, unarchive, restore, delete, like, block, unblock, reply
text string · up to 2,000 characters: The public reply. Required when action is reply. TikTok cuts replies at 150 characters and Threads at 500.

Example

Request

curl -X POST https://commentgate.com/api/v1/comments/2a8d5bac-3084-472a-92d9-700577412c23/actions \
  -H "Authorization: Bearer $COMMENTGATE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"action":"reply","text":"Thanks, Maya! Wide sizes ship in October."}'

202 Accepted. Platform work was queued: hide, unhide, delete, like, block, unblock, reply, and allow on a hidden comment.

202 Accepted response

{
  "data": {
    "comment_id": "2a8d5bac-3084-472a-92d9-700577412c23",
    "action": "reply",
    "queued": true
  }
}

200 OK. The change was local only and is already done: archive, unarchive, restore, or allow on a comment that was not hidden.

200 OK response

{
  "data": {
    "comment_id": "2a8d5bac-3084-472a-92d9-700577412c23",
    "action": "archive",
    "queued": false
  }
}

Errors

HTTP	Code	When
400	`invalid_request`	Not JSON, an unknown `action`, or `reply` without `text`
401	`unauthorized`	Missing, unknown or revoked key
403	`forbidden`	The key's creator left the workspace or can no longer moderate
404	`not_found`	No comment with that id in this workspace
409	`conflict`	The comment was already removed or deleted
422	`unprocessable`	The platform does not allow this action on this comment. The message says why, in a sentence you can show as is

Also as act_on_comment (MCP), commentgate comments hide, commentgate comments unhide, commentgate comments allow, commentgate comments archive, commentgate comments unarchive, commentgate comments restore, commentgate comments delete, commentgate comments like, commentgate comments block, commentgate comments unblock, commentgate comments reply.

Platform limits

What each platform allows, checked against the same rules the inbox uses. Anything marked no answers 422 unprocessable with the reason in words.

Action	Facebook	Instagram	TikTok	YouTube	Threads
`hide`	Yes	Yes	Yes	Yes, held for review	Top-level replies only
`unhide`	Yes	Yes	Yes	Yes	Top-level replies only
`delete`	Yes	Yes	No	No	No
`like`	Yes	Yes	Posts only, not ads	No	No
`reply`	Yes	Top-level comments only, and not hidden ones	First-level comments only, 150 characters	Top-level comments only, and not held ones	Yes, 500 characters
`block`	Yes	No	No	Yes, removes the comment for good and hides their future comments	No
`unblock`	Yes	No	No	No	No
`allow`, `archive`, `unarchive`, `restore`	Yes	Yes	Yes	Yes	Yes

Every action has its undo: hide and unhide, archive and unarchive, block and unblock, and restore for a comment someone put in the Bin. Meta will not let you block the same person again for 48 hours after unblocking them.

On YouTube, block removes the comment for good and hides the author's future comments; unblock people in YouTube Studio, under Hidden users.

In the help center

Connect Zapier and Make
Start a Zap or a Make scenario when a comment arrives, is hidden, needs you or turns into a lead, and hide, reply or record a sale from any other app.
Send sales and leads to Meta
Connect your Meta dataset so sales from your tracked links and emails people give you in DMs reach Events Manager, and your ads learn who buys.