​
Configuration

Connect to Instagram Graph API to sync media, stories, and insights for business accounts. Provide the following configuration parameters:

KeyDescriptionSample ValueRequired
access_tokenOAuth access token with Instagram Graph API permissions.EAAGm0PX4ZCpsBA...✅
ig_user_idsList of Instagram Business Account IDs to fetch data for.["1234567890", "9876543210"]✅
media_insights_lookback_daysNumber of days to look back for media insights.60Optional
start_dateStart date (ISO 8601 format) to begin fetching media and insights data.2025-01-01T00:00:00Z✅
metrics_log_levelLog level for API metrics (e.g., INFO, DEBUG, WARNING).INFOOptional

​
How to Get Your access_token

You have two options to generate an access token:

  • Click the OAuth login button in your Mage workspace.
  • Approve the required permissions for Instagram:
    • instagram_basic
    • instagram_manage_insights
    • pages_show_list
  • The access token will be securely generated and automatically populated in the configuration.

Tip: Use the OAuth flow for a smoother and safer authentication process without manually handling tokens.

​
2. Manually Generate Access Token

  • Create a Facebook App via Facebook Developer Portal.
  • Add Instagram Basic Display API and Instagram Graph API products to your app.
  • Generate a User Access Token via Graph API Explorer.
  • Make sure to select the correct Instagram-related permissions.
  • Convert the short-lived token to a long-lived token for production use.

​
What is Instagram Graph API?

The Instagram Graph API is designed for businesses and creators to access media, insights, and metrics on Instagram accounts. It enables data-driven marketing and content analysis.


​
Why Integrate Instagram with Mage?

  • Automate content extraction: Sync media posts and stories.
  • Measure engagement: Track likes, comments, saves, impressions, and reach.
  • Audience insights: Understand follower growth and demographics.
  • Marketing analytics: Integrate with other platforms for a 360-degree marketing view.

​
Supported Streams

The Instagram source extracts the following resources:

  • media: All published media objects (images, videos, carousels).
  • media_children: Children of carousel media posts.
  • media_insights: Metrics like reach, impressions, engagement for each media post.
  • stories: Instagram Stories posted by the account.
  • story_insights: Insights for each Story, including taps forward, exits, impressions.
  • user_insights_28day: Aggregated user insights over a 28-day window.
  • user_insights_daily: Daily user insights.
  • user_insights_followers: Follower count and demographic data.
  • user_insights_online_followers: Times of day when followers are online.
  • user_insights_weekly: Weekly user insights.
  • users: Profile data of the Instagram Business accounts.