Instagram - SocialAPI.AI

Available Managed connector - SocialAPI handles the Meta App and platform app review for you. No customer-side Meta for Developers registration required. See Platform credentials.

At a glance

Field	Value
Platform slug	`instagram`
Auth type	OAuth 2.0 (Meta)
API	Meta Graph API
Best for	Largest reach for visual brands; full inbound and outbound surface.

Capabilities

Feature	Supported	Notes
List posts	Yes	Returns posts, reels, carousels
List stories	Yes	Active stories only (expire about 24 hours after posting)
Comments	Yes	Scoped to a specific post
Reply to comment	Yes
Private reply	Yes	Sends a DM to the commenter
Comment replies (thread)	Yes
Like comment	No	Instagram Graph API does not expose comment likes
Moderate comment (hide/unhide/delete)	Yes
Toggle post comments	No	No route exists; planned for a future release
DMs	Yes
Send DM	Yes	Text and/or media attachment (`attachment_url`)
Send DM attachment	Yes	Image, video, audio, or file via `attachment_url` (type inferred from URL extension, max 25 MB)
Get DM thread by user	Yes
Reviews	No	Instagram has no review feature
Mentions	Yes
Create post	Yes	Images, videos, reels, carousels
Delete post	Yes

Connecting

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'

Response:

{
  "auth_url": "https://api.instagram.com/oauth/authorize?client_id=...&state=...",
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2"
}

Redirect your user to auth_url. After they authorize, SocialAPI exchanges the code with Instagram and redirects the user to your redirect_uri with the connection result. See OAuth flows for the redirect parameters.

Reading samples

List posts

curl "https://api.social-api.ai/v1/posts?account_ids={id}&limit=10" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Sample response:

{
  "data": [
    {
      "id": "p_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "text": "Hello world #socapi",
      "status": "published",
      "targets": [
        {
          "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
          "platform": "instagram",
          "platform_post_id": "17895695668004550",
          "status": "published"
        }
      ],
      "created_at": "2026-03-01T12:00:00Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "has_more": false
  }
}

List active stories

Returns the account’s currently-active stories. Stories are ephemeral: they expire about 24 hours after posting, so this endpoint only ever returns what is live right now. Instagram only.

curl "https://api.social-api.ai/v1/platforms/instagram/accounts/{id}/stories?limit=10" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Each item uses the same shape as a post. Two story-specific values are surfaced in metadata: is_story is always true, and expires_at is the computed expiry (posting timestamp plus 24 hours; Instagram does not return an expiry field). For video stories without a media_url, the cover image is returned as media_url. Sample response:

{
  "data": [
    {
      "id": "17895695668004550",
      "platform": "instagram",
      "caption": "",
      "media_type": "VIDEO",
      "media_url": "https://scontent-...",
      "permalink": "https://www.instagram.com/stories/acmecorp/17895695668004550/",
      "timestamp": "2026-06-16T12:00:00Z",
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "metadata": {
        "is_story": true,
        "expires_at": "2026-06-17T12:00:00Z"
      }
    }
  ],
  "count": 1
}

List comments on a post

Comments are scoped to a specific post. Use the platform post ID (e.g. from targets[].platform_post_id):

curl "https://api.social-api.ai/v1/inbox/comments/17895695668004550?limit=10" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Sample response:

{
  "data": [
    {
      "platform_id": "17895695668004550",
      "platform": "instagram",
      "text": "Love this!",
      "author_id": "17841400000000000",
      "author_name": "Jane Doe",
      "author_username": "janedoe",
      "author_picture": "https://scontent.cdninstagram.com/v/t51.../profile.jpg",
      "is_owner": false,
      "like_count": 3,
      "reply_count": 1,
      "has_replies": true,
      "liked_by_viewer": false,
      "is_hidden": false,
      "capabilities": {
        "can_reply": true,
        "can_delete": true,
        "can_hide": true,
        "can_like": true,
        "can_private_reply": true
      }
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": ""
  }
}

List DMs

curl "https://api.social-api.ai/v1/inbox/conversations?account_id={id}&platform=instagram&limit=10" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Sample response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "9f1b...",
      "account_id": "acct_...",
      "platform": "instagram",
      "platform_id": "aWdfZG1f...",
      "participant_id": "17841400000000000",
      "participant_name": "Jane Doe",
      "participant_picture": "https://scontent.cdninstagram.com/v/.../profile.jpg",
      "last_message": "Thanks for reaching out!",
      "last_message_at": "2026-06-20T12:00:00Z",
      "status": "active",
      "unread_count": 0,
      "created_at": "2026-06-19T09:30:00Z",
      "updated_at": "2026-06-20T12:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": ""
  }
}

Publishing

Create an Instagram post with optional platform-specific fields:

curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world #socapi",
    "media_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
    "targets": [
      {
        "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
        "platform_data": {
          "alt_text": "A product photo showing our new widget",
          "share_to_feed": true
        }
      }
    ]
  }'

For the full field reference, media constraints, and error recovery, see Instagram posts.

Limitations and gotchas

Private replies. Replying to a comment with "private": true sends a DM to the commenter. This is Instagram’s native “Send Private Reply” feature, not a SocialAPI workaround.
Token expiry. Instagram access tokens can expire. If you receive 401 with code: "invalid_token", reconnect the account using the OAuth flow.
Account fields. See the shared account object reference for the fields returned by /v1/accounts.

Permissions

Permissions. SocialAPI’s managed Meta App already requests these scopes on your behalf: instagram_business_basic, instagram_business_manage_comments, instagram_business_manage_messages, instagram_business_content_publish. You don’t need to apply for any platform app review. See Platform credentials.

​At a glance

​Capabilities

​Connecting

​Reading samples

​List posts

​List active stories

​List comments on a post

​List DMs

​Publishing

​Limitations and gotchas

​Permissions

​Related

At a glance

Capabilities

Connecting

Reading samples

List posts

List active stories

List comments on a post

List DMs

Publishing

Limitations and gotchas

Permissions

Related