> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer <your API key>.
> Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs.
> A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. Authenticated responses can carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute request budget your SocialAPI account shares across every API key (see /guides/rate-limits).
> Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page.
> Treat every ID as an opaque string: do not parse it or assume a format.
> Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. Some families return their own code instead: reviews, and posts with a target on Telegram or App Store Connect, return 422 account.platform_unsupported; Automations 422 automation.platform_unsupported.

# Instagram comments

> List, reply to, hide, delete, and like Instagram comments, and send private replies to commenters, through SocialAPI's comments API.

SocialAPI reads the comments on the posts and Reels of a connected Instagram Business or Creator account and acts on them: reply publicly, send a private reply, hide, unhide, delete, and, on accounts connected through Facebook Login, like. The endpoints are the ones every platform uses, described in [Comments](https://docs.social-api.ai/guides/comments.md). This page holds the rules that are specific to Instagram, including the differences between [Instagram Login and Facebook Login](https://docs.social-api.ai/platforms/instagram#connect-through-facebook-login).

A public reply costs 1 interaction credit. Reading, private replies, hiding, deleting, and liking cost none.

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/v1/inbox/comments?platform=instagram` | List Instagram posts that received comments |
| `GET` | `/v1/inbox/comments/{post_id}` | List the comments on one post |
| `GET` | `/v1/inbox/comments/{post_id}/{comment_id}/replies` | List the replies to one comment |
| `POST` | `/v1/inbox/comments/{post_id}` | Reply to a comment, or comment on the post |
| `POST` | `/v1/inbox/comments/{post_id}/{comment_id}/private-reply` | Send a private reply to the person who commented |
| `POST` | `/v1/inbox/comments/{post_id}/{comment_id}/hide` | Hide a comment |
| `DELETE` | `/v1/inbox/comments/{post_id}/{comment_id}/hide` | Unhide a comment |
| `DELETE` | `/v1/inbox/comments/{post_id}/{comment_id}` | Delete a comment |
| `POST` | `/v1/inbox/comments/{post_id}/{comment_id}/like` | Like a comment. Facebook Login only |
| `DELETE` | `/v1/inbox/comments/{post_id}/{comment_id}/like` | Remove that like. Facebook Login only |

`{post_id}` is the Instagram media ID: `targets[].platform_post_id` on a post you published through SocialAPI, or `id` from `GET /v1/inbox/comments`. `{comment_id}` accepts the comment's `sapi_cmt_` ID or Instagram's comment ID. See [IDs](https://docs.social-api.ai/guides/ids.md#what-each-endpoint-accepts).

## Your first reply

List the comments on a post. `account_id` is required:

```bash theme={null}
curl "https://api.social-api.ai/v1/inbox/comments/17895695668004550?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J" \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Response (HTTP 200), for an account connected through Instagram Login:

```json theme={null}
{
  "data": [
    {
      "id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I",
      "platform_id": "17858893269577012",
      "platform": "instagram",
      "text": "Is the blue one still in stock?",
      "author_id": "17841400008460056",
      "author_name": "janesmith",
      "author_username": "janesmith",
      "author_picture": "",
      "is_owner": false,
      "like_count": 2,
      "reply_count": 0,
      "has_replies": false,
      "liked_by_viewer": false,
      "is_hidden": false,
      "parent_id": null,
      "created_at": "2026-10-13T14:30:00Z",
      "capabilities": {
        "can_reply": true,
        "can_delete": true,
        "can_hide": true,
        "can_like": false,
        "can_private_reply": true
      }
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "" }
}
```

Reply to that comment in public:

```bash theme={null}
curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "comment_id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I",
    "text": "Yes, Jane, it ships today."
  }'
```

Response (HTTP 200):

```json theme={null}
{
  "success": true,
  "comment_id": "sapi_cmt_TT974YVQH4RAHNN2HY2DJSNY9111D7LMTP1X"
}
```

`comment_id` in the response is the `sapi_cmt_` ID of the new reply. Omit `comment_id` in the request to add a top-level comment to the post instead.

## Comments on Instagram

Every field of a comment is described in [List comments and replies](https://docs.social-api.ai/guides/comments.md#list-comments-and-replies). On Instagram:

* **`capabilities`.** `can_reply`, `can_delete`, `can_hide`, and `can_private_reply` are `true` on every comment and every reply. `can_like` is `true` on accounts connected through Facebook Login and `false` on accounts connected through Instagram Login.
* **`author_name`.** Instagram gives a username and no display name, so `author_name` holds the username.
* **`liked_by_viewer`.** On Instagram Login it is always `false`. On Facebook Login it can be `true` only for a like made through SocialAPI. A `true` value can read `false` later. A like made in the Instagram app never shows as `true`.
* **`is_hidden`.** A hidden comment stays in the list with `is_hidden: true`.
* **`parent_id`.** A reply carries the `platform_id` of the top-level comment it answers. A top-level comment has `parent_id: null`.
* **Paging.** A page can hold fewer comments than `limit`. Follow `next_cursor` until `has_more` is `false`: see [Pagination](https://docs.social-api.ai/guides/pagination.md#fetch-every-page).

`moderation_status`, `order`, and `q` filter only YouTube comments. On Instagram they are accepted and do not filter or sort the list.

## Reply to a comment

Instagram nests replies one level deep: a reply belongs to a top-level comment. To answer a reply, send the `platform_id` of its parent (the reply's `parent_id`) as `comment_id`. A reply posts as the connected account and is public once Instagram accepts it.

A reply costs 1 interaction credit. When the plan's interaction allowance is used up, the call returns `429 validation.interaction_limit_exhausted`. A reply sent faster than the account's sending pace allows returns `429 messaging.velocity_limit`: wait for the `Retry-After` header. See [When a credit comes back](https://docs.social-api.ai/guides/plans.md#when-a-credit-comes-back).

## Send a private reply

A private reply is a direct message (DM) to the person who wrote a comment. It opens a conversation in that person's Instagram inbox, which continues on [Instagram direct messages](https://docs.social-api.ai/platforms/instagram/messages.md).

```bash theme={null}
curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550/17858893269577012/private-reply" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "text": "Thanks for asking, Jane. Here is the blue one.",
    "buttons": [
      { "type": "url", "title": "See the product", "url": "https://shop.example.com/blue" }
    ]
  }'
```

Response (HTTP 200):

```json theme={null}
{ "success": true }
```

Instagram's rules for a private reply:

* **One per comment, within 7 days.** Instagram allows 1 private reply per comment, sent within 7 days of the comment. A second private reply, or one to a comment older than 7 days, returns `400 platform.instagram.private_reply_ineligible`. When Instagram refuses the reply, `error.meta.fbtrace_id` holds Meta's trace ID for Meta support, when Meta sends one. When the comment is already known to be ineligible, the error instead carries `error.meta.blocked_locally: true` and `error.meta.reason`: `already_replied`, `platform_refused`, or `window_expired`. When `error.meta.blocked_locally` is `true`, or the reply was text only, this 400 is final. When Instagram refuses a reply that carried `buttons` or an attachment, the refusal can come from that content: send it once more as text only.
* **No messaging window.** A private reply does not open the 24-hour [messaging window](https://docs.social-api.ai/platforms/instagram/messages.md#the-messaging-window). You can message the person again only after they answer, and their answer opens the window.
* **Content.** The request carries `text` (with up to 3 optional `buttons`, sent as a button template), or one `attachment`, not both. `text` holds at most 1,000 bytes of UTF-8, and 640 characters when it carries `buttons`. Sending `attachment` with `text` or `buttons` returns `400 validation.attachment_conflict`. Field rules are in [Send a private reply](https://docs.social-api.ai/guides/comments.md#send-a-private-reply), and Instagram's file formats and sizes are in [Message types and sizes](https://docs.social-api.ai/platforms/instagram/messages.md#message-types-and-sizes).
* **Attachment refused.** If Instagram cannot fetch or accept the file, the call returns `422 platform.instagram.attachment_failed`, and the comment can still receive its private reply.
* **Facebook Login.** An account whose Instagram account has no linked Facebook Page returns `409 platform.instagram.no_page`. Reconnect the account.

A private reply costs no credit. To send private replies by keyword with no handler of your own, use an [Automation](https://docs.social-api.ai/guides/automations.md): it sends the private reply and answers each button tap, including a [Follow gate](https://docs.social-api.ai/guides/automations.md#the-follow-gate).

## Hide, unhide, and delete a comment

Hiding removes a comment from public view on Instagram, and unhiding restores it. Deleting removes it from Instagram and cannot be undone. All three work on comments and replies on the account's posts, on both login paths.

```bash theme={null}
curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550/17858893269577012/hide" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }'
```

Response (HTTP 200):

```json theme={null}
{ "success": true }
```

Unhide with `DELETE` on the same path, and delete with `DELETE /v1/inbox/comments/{post_id}/{comment_id}`. Both take `account_id` as a query parameter and return `{ "success": true }`.

## Like a comment

Liking a comment works only on accounts connected through [Facebook Login](https://docs.social-api.ai/platforms/instagram#connect-through-facebook-login). `POST /v1/inbox/comments/{post_id}/{comment_id}/like` likes the comment as the connected account, and `DELETE` on the same path removes the like. `POST` takes `account_id` in the body, and `DELETE` as a query parameter. Both return `{ "success": true }`.

On an account connected through Instagram Login, both calls return `501 resource.not_supported`, because Instagram Login has no comment likes. Read `can_like` on the comment instead of assuming.

## Instagram Login and Facebook Login

Both login paths list, reply to, hide, unhide, and delete comments, and send private replies, in the same way. They differ in these rows:

| Feature | Instagram Login | Facebook Login |
| - | - | - |
| Like and unlike a comment | `501 resource.not_supported`, and `can_like` is `false` | Yes, and `can_like` is `true` |
| `liked_by_viewer` | Always `false` | Can be `true` only for a like made through SocialAPI, and can read `false` later |
| Private reply | Yes | Yes. Needs a linked Facebook Page, or returns `409 platform.instagram.no_page` |
| Platform scopes for comments | `instagram_business_manage_comments` | `instagram_manage_comments`, and `instagram_manage_engagement` for likes |
| Platform scope for private replies | `instagram_business_manage_messages` | `instagram_manage_messages` and `pages_messaging` |

Every scope SocialAPI requests is listed in [Instagram scopes](https://docs.social-api.ai/platforms/instagram#scopes) and [Facebook Login scopes](https://docs.social-api.ai/platforms/instagram#facebook-login-scopes).

## What Instagram does not allow

* **Replying to a reply.** Replies nest one level deep. Reply to the parent comment instead.
* **Liking a comment on Instagram Login.** Connect through Facebook Login to like comments.
* **A second private reply to the same comment, or a private reply after 7 days.** Message the person through their conversation once they answer.
* **Editing a comment.** SocialAPI has no endpoint to edit an Instagram comment. Delete it and reply again.
* **Turning comments off on a post.** SocialAPI has no endpoint to disable comments on an Instagram post. Do it in the Instagram app.
* **Commenting on a live video.** Instagram does not let apps comment on an Instagram Live broadcast.

## Limits

| Limit | Value |
| - | - |
| Private replies | 1 per comment, within 7 days of the comment |
| Private reply text | 1,000 bytes of UTF-8. 640 characters with buttons |
| Buttons on a private reply | 1 to 3 |
| Comments per page | Default 25, up to 100 |
| Replies per page | Default 10, up to 100 |
| Instagram's own rate limit | `429 platform.instagram.rate_limit`. See [Rate limits](https://docs.social-api.ai/guides/rate-limits.md#platform-limits) |

## Errors and debugging

Check these in order when an Instagram comment call fails:

1. **`403 account.permission_missing`.** The account lacks the [permission](https://docs.social-api.ai/guides/permissions.md) the call needs: `comments.read` to list comments and replies, `comments.write` to reply, hide, unhide, delete, or like, and `messages.write` for a private reply.
2. **`401 platform.instagram.auth`, `403 account.reconnection_required`.** The token is no longer valid. [Reconnect the account](https://docs.social-api.ai/guides/connect-accounts.md#reconnect-an-account).
3. **`501 resource.not_supported`.** A like or unlike on an account connected through Instagram Login.
4. **`400 platform.instagram.private_reply_ineligible`.** The comment already received its private reply, or is older than 7 days. When `error.meta.blocked_locally` is `true`, or the reply was text only, do not retry. When Instagram refuses a reply that carried `buttons` or an attachment, send it once more as text only.
5. **`422 platform.instagram.attachment_failed`.** Instagram could not fetch or accept the private reply's file. Fix the URL or the file and send again.
6. **`409 platform.instagram.no_page`.** A private reply on a Facebook Login account with no linked Facebook Page. Reconnect the account.
7. **`404 platform.instagram.100`.** Instagram says the comment or post does not exist, for example because it was deleted. Check the ID.
8. **`403 platform.instagram.200`.** The account has not granted the platform scope the call needs. Reconnect the account and approve every scope.
9. **`429 validation.interaction_limit_exhausted`, `429 messaging.velocity_limit`, `429 platform.instagram.rate_limit`, `429 platform.instagram.throttled`.** Your plan's allowance, the account's sending pace (`429 messaging.velocity_limit`: wait for the `Retry-After` header), or Instagram's own limit. `429 platform.instagram.throttled`: wait for the `Retry-After` header, then retry. Read the `Retry-After` header when it is present: see [Rate limits](https://docs.social-api.ai/guides/rate-limits.md).

Every code is in [Errors](https://docs.social-api.ai/guides/errors.md#inbox-comments-messages-and-reviews), and Instagram's own codes are in [Instagram and Facebook errors](https://docs.social-api.ai/guides/errors.md#instagram-and-facebook).

## Scopes

A [scoped API key](https://docs.social-api.ai/guides/scoped-keys.md) needs these scopes:

| Scope | Operations |
| - | - |
| `inbox:read` | List posts with comments, list comments, list replies |
| `inbox:write` | Reply, send a private reply, hide, unhide, delete, like, unlike |

## Events

SocialAPI sends `comment.received` when a person comments on, or replies to a comment on, a post of a connected Instagram account. A comment the account writes itself, in the Instagram app or through SocialAPI, sends no event. An account without the `comments.read` [permission](https://docs.social-api.ai/guides/permissions.md) receives no `comment.received` events. The payload is in [Webhook events](https://docs.social-api.ai/guides/webhook-events.md#comments).

## Use from an AI agent

| Tool | What it does |
| - | - |
| `social_api_list_inbox_posts` | List your posts with their comment counts |
| `social_api_list_post_comments` | List the comments on one post |
| `social_api_get_comment_replies` | List the replies to one comment |
| `social_api_reply_to_comment` | Reply publicly to a post or a comment. The text is 2,200 bytes at most |
| `social_api_private_reply_to_comment` | Send a private reply with text and optional buttons. The text is 1,000 bytes at most. The tool sends no attachment |
| `social_api_hide_comment`, `social_api_unhide_comment` | Hide or unhide a comment |
| `social_api_delete_comment` | Delete a comment |
| `social_api_like_comment`, `social_api_unlike_comment` | Like or unlike a comment. Facebook Login only |
| `social_api_moderate_comment` | Hide, unhide, or delete a comment by its `sapi_cmt_` ID |

The full tool list is in [MCP tools](https://docs.social-api.ai/integrations/tools.md#comments).

## Related

* [Instagram API](https://docs.social-api.ai/platforms/instagram): capabilities, connection, and scopes for Instagram
* [Instagram direct messages](https://docs.social-api.ai/platforms/instagram/messages.md): the conversation a private reply starts
* [Comments](https://docs.social-api.ai/guides/comments.md): the endpoints and fields every platform shares
* [Automations](https://docs.social-api.ai/guides/automations.md): answer Instagram comments by keyword with a private reply
* [Webhook events](https://docs.social-api.ai/guides/webhook-events.md#comments): the `comment.received` payload


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.