Instagram

Connect an Instagram professional account and you can publish every format Instagram's API allows: feed images, carousels, Stories and Reels. The same account gives you post and account insights, the DM inbox, comment moderation and comment-to-DM automations. The platform id is instagram.

#What you can do

#Connect

Instagram needs a Business or Creator account. Personal accounts cannot publish through any third-party API, so ask the user to switch their account type in the Instagram app first (it is free and takes a minute).

Start the connection with GET /v1/connect/instagram and a profileId. There are two login methods, chosen with the loginMethod query parameter:

With facebook_login the user picks the Page in a second step after OAuth. Pozy can host that picker for you, or you can build it yourself with listInstagramPages and selectInstagramAccount. See Headless connect.

curl "https://api.pozy.ai/v1/connect/instagram?profileId=6720c0f24f3b2e0018d4a6e0&loginMethod=facebook_login&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/instagram?profileId=6720c0f24f3b2e0018d4a6e0&loginMethod=facebook_login&redirect_url=https:%2F%2Fapp.example.com%2Fconnected", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

// Send the user's browser to data.authUrl

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/connect/instagram",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "profileId": "6720c0f24f3b2e0018d4a6e0",
        "loginMethod": "facebook_login",
        "redirect_url": "https://app.example.com/connected",
    },
)
print(resp.json()["authUrl"])

#Post types

Instagram decides the format from the media you send, with one field to override it. Every post needs media: there are no text-only Instagram posts.

#Feed post

curl -X POST https://api.pozy.ai/v1/posts \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "First light over the harbour. #morning",
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/harbour.jpg", "altText": "Fishing boats at dawn" }
    ],
    "platforms": [
      { "platform": "instagram", "accountId": "6720c1a94f3b2e0018d4a7f1" }
    ],
    "publishNow": true
  }'

const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "First light over the harbour. #morning",
    mediaItems: [
      { type: "image", url: "https://cdn.example.com/harbour.jpg", altText: "Fishing boats at dawn" },
    ],
    platforms: [{ platform: "instagram", accountId: "6720c1a94f3b2e0018d4a7f1" }],
    publishNow: true,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

console.log(data.post.platforms[0].platformPostUrl);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "content": "First light over the harbour. #morning",
        "mediaItems": [
            {"type": "image", "url": "https://cdn.example.com/harbour.jpg", "altText": "Fishing boats at dawn"}
        ],
        "platforms": [{"platform": "instagram", "accountId": "6720c1a94f3b2e0018d4a7f1"}],
        "publishNow": True,
    },
)
print(resp.json()["post"]["platforms"][0]["platformPostUrl"])

altText applies to feed images and carousel images. Instagram cuts it at 1,000 characters and ignores it on Reels, Stories and video slides.

#Carousel

Put up to 10 images and videos in mediaItems. Mixed media is fine. Crop everything to the same ratio before you upload, because Instagram uses the first item's ratio for all of them.

"mediaItems": [
  { "type": "image", "url": "https://cdn.example.com/menu-1.jpg" },
  { "type": "image", "url": "https://cdn.example.com/menu-2.jpg" },
  { "type": "video", "url": "https://cdn.example.com/kitchen.mp4" }
]

#Reel

A single video is always a Reel. Set shareToFeed: false to keep it in the Reels tab only, and give it a cover with instagramThumbnail (a JPEG or PNG URL, 1080 x 1920 px works best) or a frame offset in milliseconds with thumbOffset.

{
  "platform": "instagram",
  "accountId": "6720c1a94f3b2e0018d4a7f1",
  "platformSpecificData": {
    "shareToFeed": true,
    "instagramThumbnail": "https://cdn.example.com/reel-cover.jpg",
    "audioName": "Studio session"
  }
}

Trial Reels are shown to non-followers first. Add trialParams.graduationStrategy: MANUAL (you promote it yourself in the app) or SS_PERFORMANCE (Instagram shares it with followers if it performs well).

Catalog audio. audioConfiguration attaches a track from Instagram's audio library. Find an audioId with Search Instagram audio (leave out q to get what is trending), then send it with optional audioVolume and videoVolume from 0 to 100. This needs facebook_login. If the track is pulled before a scheduled Reel goes out, the post fails with a message naming the cause rather than publishing with different sound. Get Instagram audio metadata re-checks a stored id before publish time.

muteAudio: true removes the video's own sound track before upload, so the result is permanently silent. Videos over 200 MB cannot be muted.

#Story

Add contentType: "story". Stories show no caption, last 24 hours and cannot carry link stickers through the API. A Story publishes one media item, so give a Story entry its own customMedia when the post has several.

To publish a feed post and a Story of the same campaign at once, list the account twice:

"platforms": [
  { "platform": "instagram", "accountId": "6720c1a94f3b2e0018d4a7f1" },
  {
    "platform": "instagram",
    "accountId": "6720c1a94f3b2e0018d4a7f1",
    "customMedia": [{ "type": "image", "url": "https://cdn.example.com/story-1080x1920.jpg" }],
    "platformSpecificData": { "contentType": "story" }
  }
]

Each entry publishes and reports its status separately.

#Platform fields

All of these go in platformSpecificData on the Instagram entry (schema: InstagramPlatformData).

If a collaborator cannot be invited, the post still publishes and the name comes back in droppedCollaborators with a reason.

#Media requirements

Pozy compresses images over 8 MB and keeps your original. Media URLs must return the file itself: sharing links from Google Drive, Dropbox, OneDrive or iCloud return a web page and fail. Upload files with Media uploads when you do not have a direct URL.

Images

Videos

#Limits

Read how much of the 24-hour allowance is left with Get Instagram publishing limit. Compare quotaUsage with the returned quotaTotal instead of hardcoding 100, since Instagram can change the cap.

Instagram's API does not support Story stickers (polls, links, countdowns), product tags, filters, Guides or going live. Published Instagram posts cannot be edited or deleted through the API; change them in the Instagram app.

#Analytics

GET /v1/analytics?platform=instagram returns per-post impressions, reach, likes, comments, shares, saves and views, plus Reel watch-time fields (igReelsAvgWatchTime, igReelsVideoViewTotalTime) where Instagram reports them.

Account-level endpoints go further:

Story numbers are only readable while the Story is live. After 24 hours you get final numbers only if Instagram sent them before expiry, which happens far more reliably on accounts connected with facebook_login. If you need final Story metrics, read them before the Story expires. Counts under 5 can come back as 0 because of Instagram's privacy floor.

Image and cover URLs in analytics responses are served from Pozy storage and do not expire, so you can cache them.

#Inbox

Direct messages. List conversations, read messages and reply with Send message. You can send text, images (PNG, JPEG up to 8 MB), video and audio (up to 25 MB), PDFs, up to 13 quick replies, up to 3 buttons (the text must then be 640 characters or less) and product cards of up to 10 elements. Reactions work both ways.

Instagram does not expose the Message Requests folder separately, so GET /v1/inbox/conversations?folder=requests returns 400 with code PLATFORM_LIMITATION. Requests still reach you as message.received once the person writes, and Accept a message request works on them.

When another app owns a thread through Instagram's handover protocol, inbound messages arrive with metadata.standby: true, automations stay quiet and sends return 409 not_thread_owner. Move the thread with thread control.

Conversations and senders can carry an instagramProfile object (isFollower, isFollowing, followerCount, isVerified). Instagram only reveals the follow relationship for people who have messaged the account, so treat a missing value as unknown, not as "not a follower".

When you connect an account, Pozy imports its existing DM history (up to 500 conversations, the newest 500 messages in each). The import runs in the background, arrives already read and fires no webhooks.

Comments. List comments, post a top-level comment, reply, hide, unhide and delete. Send private reply opens a DM from a comment, once per comment, within 7 days. Liking a comment is in limited release on Instagram's side and only works on facebook_login accounts; other accounts get 403 PLATFORM_BETA_RESTRICTED or 400 instagram_likes_require_facebook_login.

Conversation starters. Set up to 4 ice breakers (80 characters each) and a persistent menu (3 top-level items, 5 nested). A menu postback with payload pozy:workflow:<workflowId> starts that workflow. See Conversation starters.

#Errors you may see

When a post sent with publishNow: true is rejected, the response is 207 with post.status: "failed" and the reason in platforms[].errorMessage. A 207 is still a 2xx, so check post.status rather than only the HTTP status.

#Endpoints

#Webhook events