Skip to main content
Instagram is a social media platform for sharing photos, videos, and stories. The Instagram Business API provides access to insights and analytics about your business account’s performance and audience engagement.

​
Requirements

Before setting up Instagram as a data source, ensure your account meets these requirements:
  • The Instagram account must be a Business account (personal accounts are not supported)
  • The Instagram profile must have at least 100 followers
  • The Instagram profile must be linked to a Facebook page
  • The user connecting the account must have one of these roles on the Facebook page:
    • Owner
    • Administrator
    • Editor
Instagram Limitations:
  1. Media insights (such as views and engagement metrics) are only available for content that has received at least 5 views.
  2. Stories data is only available for 24 hours after posting. If your pipeline runs during this window, the data will be captured and stored in your destination, but new pipelines won’t be able to fetch stories older than 24 hours.

​
Configuring Instagram as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Instagram option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

You’ll need to add the following information to connect to Instagram:
  1. Complete Facebook authorization with an account that has access to the page you want to get data from.
  2. Select the Instagram Page you’d like to extract data from.
  3. Define a date to be the starting point of the data retrival.
  4. The lookback window parameter allows you to define the the number of days to look in the past for new updates in Media (such as Comments and Likes). What the lookback does is check data from X days ago to ensure it captures all new updates. You can use default value if you are not sure about it.
Click Next.

​
2. Select streams

Choose which data streams you want to sync - you can select all streams or pick specific ones that matter most to you.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select a name for each table (which will contain the fetched data) and the type of sync.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data - which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can determine when to execute a full sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Streams and Fields

Below you’ll find all available data streams from Instagram and their corresponding fields:
Stream for basic account information.Key Fields:
  • id - Account ID (Primary Key)
  • ig_id - Instagram internal ID
  • username - Account username
  • name - Account display name
Profile Information:
  • biography - Account bio text
  • website - Account website URL
  • profile_picture_url - Profile picture URL
Metrics:
  • follows_count - Number of accounts being followed
  • followers_count - Number of followers
  • media_count - Total number of media posts
Stream for posts, stories, and reels.Key Fields:
  • id - Media ID (Primary Key)
  • ig_id - Instagram internal ID
  • caption - Post caption text
  • media_type - Type of media (image, video, carousel)
  • media_product_type - Product type (FEED, STORY, REELS)
  • timestamp - When the media was posted
URLs and References:
  • media_url - URL to the media content
  • permalink - Permanent link to the post
  • thumbnail_url - Thumbnail image URL
  • shortcode - Short code for the media
Engagement Metrics:
  • comments_count - Number of comments
  • like_count - Number of likes
Additional Information:
  • is_comment_enabled - Whether comments are enabled
  • is_shared_to_feed - Whether shared to feed
  • username - Username who posted
  • owner - Owner information (id)
  • boost_eligibility_info - Boost eligibility (eligible_to_boost)
Stream for media performance metrics.Key Fields:
  • media_id - Media ID (Primary Key)
  • media_product_type - Type of media (FEED, STORY, REELS)
  • timestamp - When the insights were recorded
Common Metrics:
  • comments - Number of comments
  • likes - Number of likes
  • reach - Number of unique accounts that saw the post
  • shares - Number of shares
  • total_interactions - Total engagement count
Feed Post Metrics:
  • profile_activity - Activity on profile from post
  • profile_visits - Profile visits from post
  • saved - Number of saves
  • views - Number of views
Story Metrics:
  • navigation - Story navigation metrics
  • profile_activity - Activity on profile from story
  • profile_visits - Profile visits from story
  • replies - Number of replies
Reels Metrics:
  • ig_reels_avg_watch_time - Average watch time
  • ig_reels_video_view_total_time - Total view time
  • saved - Number of saves
  • views - Number of views
Stream for post comments.Key Fields:
  • id - Comment ID (Primary Key)
  • media_id - ID of the media being commented on
  • text - Comment text
  • timestamp - When the comment was posted
Engagement:
  • like_count - Number of likes on the comment
  • hidden - Whether the comment is hidden
Stream for replies to comments.Key Fields:
  • id - Reply ID (Primary Key)
  • parent_comment_id - ID of the parent comment
  • text - Reply text
  • timestamp - When the reply was posted
Engagement:
  • like_count - Number of likes on the reply
  • hidden - Whether the reply is hidden
Stream for account-level insights with different time windows.Available Time Windows:
  • Daily (insights_rolling_day)
  • Weekly (insights_rolling_week)
  • 28 Days (insights_rolling_days28)
Key Fields:
  • date - Date of the metrics (Primary Key)
Metrics:
  • reach - Number of unique accounts reached
  • total_interactions - Total engagement count
  • accounts_engaged - Number of accounts that engaged
  • likes - Number of likes
  • shares - Number of shares
  • replies - Number of replies
  • follows_and_unfollows - Follow/unfollow activity
  • profile_links_taps - Profile link clicks
  • website_clicks - Website clicks
  • profile_views - Profile views
Stream for follower demographic information.Available Breakdowns:
  • Country (follower_demographics_country_lifetime)
  • Age (follower_demographics_age_lifetime)
  • Gender (follower_demographics_gender_lifetime)
  • City (follower_demographics_city_lifetime)
Key Fields:
  • dimension_value - The demographic value (e.g., country name, age range) (Primary Key)
  • value - Number of followers in this demographic

​
Data Model

The following diagram illustrates the relationships between the core data streams in Instagram. The arrows indicate the join keys that link the different entities.
⌘I