Instagram

Instagram

Manage Instagram professional accounts through Meta's Graph API v25.0.

Setup

Requires environment variables in .env:

INSTAGRAM_ACCESS_TOKEN=<long-lived-token>
INSTAGRAM_BUSINESS_ACCOUNT_ID=<ig-account-id>

For setup instructions, see references/authentication.md.

Running Commands

Load .env then run. Use the absolute path to the skill's scripts directory:

set -a && source .env && set +a && python3 scripts/ig_api.py <command> [options]

The script path is relative to this skill's directory. If running from elsewhere, use the full path to scripts/ig_api.py.

Commands

Profile & Account

python3 scripts/ig_api.py get_profile
python3 scripts/ig_api.py get_pages
python3 scripts/ig_api.py validate_token

Media & Posts

python3 scripts/ig_api.py get_media --limit 10
python3 scripts/ig_api.py get_media --after <cursor>
# Official metrics: engagement, impressions, reach
python3 scripts/ig_api.py get_media_insights --media-id <id>

Publish Image or Video

Always confirm with user before publishing.

# Image (JPEG only)
python3 scripts/ig_api.py create_container --image-url <public-jpeg-url> --caption "Caption" --alt-text "Description"

# Video
python3 scripts/ig_api.py create_container --video-url <public-url> --caption "Caption"

# Check status — poll until FINISHED
python3 scripts/ig_api.py check_status --container-id <id>

# Publish
python3 scripts/ig_api.py publish_media --container-id <id>

Publish Reel

# All-in-one (creates container, waits, publishes)
python3 scripts/ig_api.py publish_reel --video-url <url> --caption "Caption"

# With options
python3 scripts/ig_api.py publish_reel --video-url <url> --caption "Caption" --thumb-offset 2000 --no-feed

# Trial reel (shared to non-followers only)
python3 scripts/ig_api.py publish_reel --video-url <url> --trial MANUAL

Publish Story

python3 scripts/ig_api.py publish_story --image-url <jpeg-url>
python3 scripts/ig_api.py publish_story --video-url <video-url>

Publish Carousel (2-10 items)

# All-in-one (creates children, waits, creates parent, publishes)
python3 scripts/ig_api.py publish_carousel \
  --media-urls "https://example.com/img1.jpg,https://example.com/img2.jpg" \
  --caption "Carousel post"

# Mixed media — prefix videos with video:
python3 scripts/ig_api.py publish_carousel \
  --media-urls "https://example.com/img1.jpg,video:https://example.com/clip.mp4" \
  --caption "Mixed carousel"

Rate Limits & Status

python3 scripts/ig_api.py publishing_limit
python3 scripts/ig_api.py check_status --container-id <id>

Analytics

# Official metrics: impressions, reach, profile_views
python3 scripts/ig_api.py get_account_insights --period day
python3 scripts/ig_api.py get_account_insights --period days_28 --metrics impressions,reach

Deprecated (Jan 2025): video_views, email_contacts, website_clicks — do not use.

Direct Messages (Advanced Access)

python3 scripts/ig_api.py get_conversations --limit 10
python3 scripts/ig_api.py get_messages --conversation-id <id>
python3 scripts/ig_api.py send_dm --recipient-id <id> --message "Hello!"

Rules

• Always load .env before running: set -a && source .env && set +a
• Never expose access tokens or credentials in output
• Always confirm with user before publishing
• See references/api_reference.md for rate limits, image format restrictions, and all API limitations

Resources

• API reference: references/api_reference.md — all endpoints, params, rate limits, error codes
• Auth setup: references/authentication.md — token generation and permissions