Instagram API
The Instagram Graph API is the exclusive official interface for programmatic Instagram access — content publishing, DM management, insights, comment moderation, and branded content. Business or Creator accounts only.
API Overview
2026 EditionThe Instagram Graph API is Meta's official API for Instagram Business and Creator accounts. Following the retirement of the Basic Display API in late 2024, all integrations must use the Graph API. It provides content publishing, comment moderation, DM inbox management, and detailed analytics.
2026 Additions: New is_ai_generated parameter for media transparency, Paid Partnership / Branded Content labels via the API, and expanded audience demographic metrics. Personal accounts are not supported.
API Features
| Feature | Description | Required Permission | Status |
|---|---|---|---|
| Photo Publishing | Publish single images to the feed | instagram_business_content_publish | Available |
| Reels Publishing | Publish short-form video Reels | instagram_business_content_publish | Available |
| Carousel Publishing | Publish multi-image/video carousel posts | instagram_business_content_publish | Available |
| Stories | Publish Stories (24h ephemeral content) | instagram_business_content_publish | Available |
| AI Disclosure Flag | Mark content as AI-generated using is_ai_generated parameter | instagram_business_content_publish | New 2026 |
| Branded Content API | Publish posts with Paid Partnership labels and brand partner tags | instagram_branded_content_ads_brand | New 2026 |
| Media Insights | Retrieve per-post engagement metrics | instagram_business_basic | Available |
| Webhook Events | Real-time notifications for comments, mentions, and messages | Webhook subscription setup | Available |
Rate Limits
2026 Framework| Limit Type | Value | Window | Notes |
|---|---|---|---|
| Per-User API Calls | 200 calls / hour | Rolling 1 hour | Hard cap — most endpoints |
| Publishing Cap | 100 posts / 24 hours | Rolling 24 hours | Per Instagram account |
| Graph Call Budget (BUC) | 4,800 × Impressions | Rolling 24 hours | For broader data retrieval endpoints |
| Automated DMs | ~200 messages / hour | Rolling 1 hour | Per account |
Use Webhooks instead of polling to minimize API calls. When rate limits are exceeded, the API returns HTTP 429. Implement exponential backoff with jitter in all retry logic.
Media Requirements
No Direct File Upload: The Instagram Graph API uses a container-based model. You must provide a publicly accessible URL to your media — Meta's servers fetch (curl) it directly. There is no direct file upload endpoint.
| Content Type | Formats | Max Size | Aspect Ratio | Duration |
|---|---|---|---|---|
| Feed Photo | JPG, PNG | 8 MB | 4:5 to 1.91:1 | — |
| Reels / Video | MP4, MOV (H.264, AAC) | 1 GB | 9:16 (preferred) | 3s – 15 min |
| Carousel Items | JPG, PNG, MP4, MOV | — | 1:1 recommended | — |
| Stories Photo | JPG, PNG | 8 MB | 9:16 (1080×1920 px) | — |
| Stories Video | MP4, MOV | 1 GB | 9:16 | Up to 60 seconds |
| Min Resolution | 320 pixels on the shortest side | |||
Authentication & Access Requirements
| Requirement | Details |
|---|---|
| Account Type | Instagram Business or Creator account required. Personal accounts not supported. |
| Facebook Page Link | Instagram account must be linked to a Facebook Page. |
| Auth Method | OAuth 2.0 via Meta's Facebook Login |
| App Review | Required for production permissions. Submit for review in the Meta App Dashboard. |
| Page Publishing Auth (PPA) | If your linked Facebook Page requires PPA, it must be completed before the API will allow publishing. |
| 2FA | Required for accounts linked to apps performing sensitive actions. |
Key Permission Scopes
Quick Start Guide
Set Up Meta App & Permissions
Create a Meta App at developers.facebook.com, add Instagram Graph API product, and request required permissions. Ensure your Instagram account is Business/Creator and linked to a Facebook Page.
Step 1 — Create a Media Container
POST https://graph.facebook.com/v26.0/{ig-user-id}/media
?image_url=https://your-public-server.com/image.jpg
&caption=Hello+from+the+API
&access_token=YOUR_ACCESS_TOKENResponse returns a creation_id.
Step 2 — Publish the Container
POST https://graph.facebook.com/v26.0/{ig-user-id}/media_publish
?creation_id=CREATION_ID
&access_token=YOUR_ACCESS_TOKENRetrieve Post Insights
GET https://graph.facebook.com/v26.0/{media-id}/insights
?metric=impressions,reach,likes
&access_token=YOUR_ACCESS_TOKENCommon Errors & Solutions
| Error Code | Meaning | Common Cause | Solution |
|---|---|---|---|
| 190 | Invalid Access Token | Expired or revoked token | Re-authenticate user and obtain a fresh long-lived token |
| 4 (100) | Publishing limit reached | Exceeded 100 posts per 24-hour window | Wait for the rolling 24-hour window to reset before publishing more |
| 9007 | User not eligible | Account is not a Business or Creator account | Convert Instagram account to Business or Creator type in the app settings |
| 2207027 | Media not ready | Video container not yet processed | Poll the container status field and only publish when STATUS = FINISHED |
| 24 | PPA not completed | Page Publishing Authorization not done | Complete PPA for the linked Facebook Page |
Best Practices
Host Media on Public CDN
Always host your images and videos on a publicly accessible server or CDN. Meta's servers must be able to fetch the URL directly without authentication.
Poll Container Status
For video uploads, poll the container's status_code field before calling media_publish. Only publish when STATUS = FINISHED.
Subscribe to Webhooks
Use Webhooks for comment notifications and message events instead of polling to minimize API call consumption against the 200/hr rate limit.
Flag AI-Generated Content
Set is_ai_generated=true on all AI-created media when creating media containers. Required for policy compliance since 2026.