Instagram Business
API Documentation: Instagram Business API Documentation
High-Level Information:
The Instagram Business API provides access to various types of data related to business accounts on Instagram. It includes insights on account performance, media engagement (such as likes, comments, and shares), follower demographics, and ad performance. The API also allows retrieval of post and story metrics, mentions, hashtags, and messages from Direct Messaging. This data enables businesses to analyze audience interactions, track campaign effectiveness, and manage content more efficiently within their marketing and analytics platforms.
Source Setup Guide
Step 1
in the Edit Source form to the left.
Step 2
Follow the authentication flow (OAuth) in Facebook's website to grant Extract the required permissions.
Step 3
Confirm you can see your email and profile picture, and that the source is Connected.
Connection Setup Guide
After you connect Instagram Business to a destination, configure the connection settings:
- Connection Pull Schedule: How frequently Extract syncs data from Instagram.
- Backfill (Days): How many days of historical data to retrieve on each run.
- Destination-specific settings: Options like Dataset Name or Target Schema (varies by destination).
- Schema Migration Policy: How Extract should handle schema changes from the source.
Schema ERD
Explore the interactive entity relationship diagram for Instagram.
Data Streams
ig_media
ig_user
lifetime_media_insights_by_action_type
lifetime_media_insights_by_story_navigation_action_type
media_comments
media_insights
user_daily_insights_by_contact_button_type
user_daily_insights_by_follow_type
user_daily_insights_by_media_product_type
user_insights_daily
Troubleshooting
-
No linked Instagram professional accounts are accessible
- Symptom: Setup or sync fails with an error indicating no linked Instagram professional accounts can be accessed.
- Cause: The connector can only read Instagram professional (Business/Creator) accounts that are linked to a Facebook Page and authorized via Facebook.
- Fix:
- Confirm each Instagram account is a professional account.
- Link each Instagram professional account to a Facebook Page.
- Reconnect the source and ensure you grant access to the relevant Pages.
-
Facebook did not return a Page access token
- Symptom: Setup or sync fails with an error like: “Facebook did not return a Page access token. Reconnect and grant Page access.”
- Cause: The authorization did not include sufficient Page permissions, or Page access was not granted/approved during OAuth.
- Fix: Reconnect the source and, when prompted, grant access to the Facebook Pages that are linked to the Instagram professional accounts you want to sync.
-
Partial access / revoked permissions
- Symptom: A sync fails after permissions change (for example, you removed Page access or an admin changed roles).
- Behavior: The connector validates access to the selected accounts before emitting rows. If access is revoked for any selected account, the sync fails rather than returning an incomplete snapshot.
- Fix: Reconnect and re-authorize with access to all selected Pages/accounts, or update the account selection to only include accounts you can still access.
-
Media insights errors for older posts
- Symptom: Sync fails or media insights are missing for some posts, especially older content.
- Cause: Instagram may reject insights for media posted before the account was converted to a professional (business/creator) account.
- Fix: Limit reporting expectations for pre-conversion media. If you need a clean run, adjust your sync window (if applicable) to start after the conversion date.
-
Unsupported media insight metrics
- Symptom: Sync fails with an error indicating Instagram rejected unsupported media insight metrics.
- Cause: Instagram can reject certain insight metrics depending on media type, API changes, or account eligibility.
- Fix: Retry later (in case of transient API behavior). If the issue persists, contact support with the failing stream name and the error message so we can adjust the requested metrics set.