Instagram Publishing API: How to Publish and Schedule Posts

The Instagram Publishing API lets approved apps publish images, videos, Reels, and carousels to eligible Instagram professional accounts. The catch is that publishing is a two-step container workflow, not a direct file upload endpoint.

Supported account types

• Instagram Business accounts connected to a Facebook Page.
• Instagram Creator accounts where the selected Meta flow and permissions support publishing.
• Accounts authorized through a Meta app that has passed the required review for production use.

The native Meta workflow

1. Authenticate the user with Meta OAuth.
2. Find the Facebook Page and connected Instagram user ID.
3. Create a media container with image_url or video_url.
4. Wait until the container is ready when video processing is involved.
5. Publish the container using the media_publish edge.

async function createInstagramImageContainer({ igUserId, accessToken, imageUrl, caption }) {
  const params = new URLSearchParams({
    image_url: imageUrl,
    caption,
    access_token: accessToken
  });

  const res = await fetch(
    `https://graph.facebook.com/v23.0/${igUserId}/media`,
    { method: "POST", body: params }
  );

  if (!res.ok) throw new Error(await res.text());
  return res.json(); // { id: "creation_container_id" }
}

async function publishInstagramContainer({ igUserId, accessToken, creationId }) {
  const params = new URLSearchParams({
    creation_id: creationId,
    access_token: accessToken
  });

  const res = await fetch(
    `https://graph.facebook.com/v23.0/${igUserId}/media_publish`,
    { method: "POST", body: params }
  );

  if (!res.ok) throw new Error(await res.text());
  return res.json(); // { id: "instagram_media_id" }
}

Images, Reels, and carousels

Publishing limits

Meta documents a moving 24-hour publishing cap for API-published Instagram posts, and carousels count as a single post. Apps should track account-level usage, warn before the limit is hit, and avoid retry loops that accidentally consume attempts.

Scheduling Instagram posts

For SaaS scheduling, the durable approach is to store the planned post, validate media early, refresh credentials before publish time, and run the container/publish workflow at the scheduled timestamp.

await socialcast.posts.create({
  platforms: ["instagram"],
  text: "Behind the scenes from launch week.",
  media: [{ type: "image", url: "https://cdn.example.com/launch.jpg" }],
  account_ids: ["ig_17841400000000000"],
  publish_at: "2026-08-12T18:30:00Z"
});

Common errors

• The Instagram account is not a supported professional account.
• The Facebook Page and Instagram user are not connected as expected.
• The image or video URL is not public, expires too soon, or returns the wrong content type.
• A video container is not ready when media_publish is called.
• The account has hit a publishing limit or the app lacks approved permissions.

How SocialCast removes the Meta workflow complexity

SocialCast turns Meta's native workflow into one API call. It manages OAuth, account discovery, media validation, container creation, video readiness checks, carousel assembly, scheduling, retries, and final publish status. Your product does not need to build a separate Meta job runner before shipping Instagram publishing.