Instagram Graph API

Version: v21.0 | Base: https://graph.instagram.com/v21.0

Quick Reference

Two-Phase Publishing

1. Create Container → container_id
2. (Video only) Poll until FINISHED
3. Publish Container → post_id

Publishing Functions

python
1from app.instagram_helper import (
2    post_photo_to_instagram,
3    post_video_to_instagram,
4    post_carousel_to_instagram
5)
6
7# Image
8result = await post_photo_to_instagram(image_url, caption)
9
10# Reels
11result = await post_video_to_instagram(video_url, caption)
12
13# Carousel (2-10 images)
14result = await post_carousel_to_instagram(image_urls, caption)

Video Requirements

python
1# Auto-convert
2from app.instagram_helper import convert_video_for_instagram
3result = await convert_video_for_instagram(input_path)
4# Returns: {success, output_path, converted, file_size_mb}

Insights

python
1from app.insights_helper import get_instagram_media_insights
2
3insights = await get_instagram_media_insights(media_id)
4# Returns: {plays, reach, saves, shares, likes, comments, engagement_rate}

Reels metrics: plays, reach, saved, shares, comments, likes Image metrics: impressions, reach, saved

Rate Limiting

• Container creation: 2s delay
• Video polling: 10s interval, max 30 attempts
• Insights fetch: 0.3s delay between calls

Environment Variables

bash
1INSTAGRAM_ACCESS_TOKEN=...
2INSTAGRAM_USER_ID=...
3INSTAGRAM_BUSINESS_ID=...  # Optional

Return Format

python
1# Success
2{"success": True, "id": "17901234567890123", "platform": "instagram"}
3
4# Error
5{"success": False, "error": "Error message"}

Common Errors

Deep Links

• app/instagram_helper.py - Publishing
• app/insights_helper.py - Metrics
• app/cloudinary_helper.py - Video CDN