Instagram content publishing API
Instagram Content Publishing API for Business Accounts
Instagram publishing in Wahdx Connection targets business and creator accounts connected through Meta. The same content endpoint used for the other platforms handles photos, carousels, and video, so an Instagram post is one prepared payload rather than a separate integration. Stories are not part of the API. This page covers the account requirement, the media rules, the carousel limits, and the metrics you can read back per account.
What the Instagram API can do
The API publishes the three media types Instagram accepts through its Content Publishing API: single photos, photo carousels, and video, including reels. It schedules posts up to 30 days ahead, reports queued, processing, published, or failed status per post, and returns account analytics. Because Instagram is one of five platforms on the same endpoint, the payload shape you build here also works for TikTok, Threads, Facebook, and YouTube.
- Single photo, photo carousel, and video publishing.
- Reels publishing through the same content endpoint.
- Schedule up to 30 days ahead.
- Per-account analytics after publishing.
Business account requirements
Instagram publishing through the API requires a business or creator account connected through Instagram Login. Personal accounts cannot publish. The connection is consent-based, the scopes you approve are visible when the account is added, and the account then appears in the account listing endpoint with an accountId. Expired accounts are still returned so your interface can prompt for reconnection, but publishing requires an active account.
- Business or creator account, not a personal profile.
- Connected through Instagram Login with visible scopes.
- Publishing requires an active account.
Media requirements and carousel rules
A carousel supports up to 10 media items and must stay photo-only; mixing stills and video in one carousel is rejected. Images can use JPEG, PNG, WebP, or GIF where the platform supports them, and video follows the same format profile as the other platforms. The backend detects the media type from the URL extensions in mediaItems, so one image URL produces a photo post and multiple image URLs produce a carousel without changing the endpoint.
| Media type | Limit |
|---|---|
| Photo | Single image |
| Carousel | Up to 10 photo items, photo-only |
| Video and reels | Single video, platform format rules apply |
| Stories | Not supported |
| Text-only | Not supported |
Publishing limits and scheduling
Posts can be published immediately or scheduled up to 30 days ahead. A carousel counts as one post regardless of how many items it carries. The queue is processed server-side, and every scheduled post is validated against the selected account before it is queued, so an incompatible media type fails early rather than at publish time. Failed posts remain visible in status tracking.
Publish sequence: endpoint to endpoint
An Instagram post is three calls. List connected accounts to find the Instagram accountId. Send the media to POST /api/content/post with the platform set to instagram and one image, several images, or one video URL in mediaItems. Then poll GET /api/content/status/:accountId/:publishId until the post is published or failed. The platform field must match the connected account platform, or the request is rejected.
const API_BASE_URL = 'https://api.wahdx.com';
const API_KEY = process.env.WAHDX_API_KEY;
await fetch(API_BASE_URL + '/api/content/post', {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(
{
"platform": "instagram",
"accountId": "acc_instagram_internal_uuid",
"content": "Campaign post caption",
"mediaItems": [
{
"url": "https://your-domain.com/video.mp4"
}
],
"instagramSettings": {
"share_to_feed": true
}
}
)
});import os
import requests
API_BASE_URL = 'https://api.wahdx.com'
API_KEY = os.environ['WAHDX_API_KEY']
response = requests.post(
API_BASE_URL + '/api/content/post',
headers={
'X-API-Key': API_KEY,
'Content-Type': 'application/json',
},
json={
'platform': 'instagram',
'accountId': 'acc_instagram_internal_uuid',
'content': 'Campaign post caption',
'mediaItems': [
{
'url': 'https://your-domain.com/video.mp4'
}
],
'instagramSettings': {
'share_to_feed': True
}
},
timeout=30,
)
response.raise_for_status()
print(response.json())curl -X POST "https://api.wahdx.com/api/content/post" \
-H "X-API-Key: $WAHDX_API_KEY" \
-H "Content-Type: application/json" \
--data-raw '{
"platform": "instagram",
"accountId": "acc_instagram_internal_uuid",
"content": "Campaign post caption",
"mediaItems": [
{
"url": "https://your-domain.com/video.mp4"
}
],
"instagramSettings": {
"share_to_feed": true
}
}'Reading metrics back
Instagram analytics cover reach, profile views, interactions, accounts engaged, and follower demographics where the platform exposes them. The values come back per connected account, tied to the account that published, so a report can separate a change in reach on one account from the whole workspace. Metrics the platform does not provide return null instead of an estimate.
FAQ
Common questions about the Instagram API
Can I publish to Instagram with a personal account?
No. Instagram publishing through the API requires a business or creator account connected through Instagram Login.
How many photos can an Instagram carousel contain?
Up to 10 media items. Carousels must be photo-only, and mixing photos with video is rejected.
Does the API support Instagram Stories?
No. The content publishing API handles feed photos, carousels, and video, including reels. Stories are not supported.
Which metrics does Instagram analytics return?
Reach, profile views, interactions, accounts engaged, and follower demographics where the platform exposes them.
Related reading
Go deeper on this workflow.
Related API docs
TikTok Content Publishing API: Video, Photos & Carousels
Publish video and photo carousels to TikTok through an official API. Media specs, posting limits, QR login, scheduling, and status tracking in one workflow.
YouTube API: Upload Videos and Read Channel Analytics
Upload videos to YouTube with per-video settings, then read subscribers, views, and video metrics through one API workflow.
Threads API: Text Posts, Thread Sequences & Metrics
Publish text posts and thread sequences to Threads via API. Character limits, scopes, reply settings, rate limits, and metrics read-back.
Facebook Graph API Page Publishing and Insights
Publish to Facebook Pages and read back unique impressions, post engagements, page views, and follows through one API workflow for content teams.