Advanced Analytica Advanced Analytica: IBOM
← All connectors
Instagram logo

Source connector

Instagram

Set up Instagram as a source and move its data into your chosen destination.

Version 4.2.51 certified generally available

Instagram

Use this page to set up the Instagram source connector and find reference information.

Prerequisites

  • A Facebook app with the Instagram Graph API enabled
  • An access token with these permissions: instagram_basic, instagram_manage_insights, pages_show_list, pages_read_engagement

Set up the connector

Set up Instagram

Airbyte Cloud

  1. Have a Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Instagram from the Source type dropdown.
  4. Enter a name for the Instagram connector.
  5. Click Authenticate your Instagram account.
  6. Log in and authorise the Instagram account.
  7. (Optional) Enter the Start Date in YYYY-MM-DDTHH:mm:ssZ format. This date only applies to the User Insights stream. The connector replicates all data generated after this date. If left blank, the start date is set to two years before the present date.
  8. Click Set up source.

Airbyte Open Source

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Instagram from the Source type dropdown.
  4. Enter a name for your source.
  5. Enter the Access Token generated using the Graph API Explorer. Alternatively, enter a Facebook app with these permissions: instagram_basic, instagram_manage_insights, pages_show_list, pages_read_engagement.
  6. (Optional) Enter the Start Date in YYYY-MM-DDTHH:mm:ssZ format. This date only applies to the User Insights stream. The connector replicates all data generated after this date. If left blank, the start date is set to two years before the present date.
  7. Click Set up source.

Supported sync modes

The Instagram source connector supports these sync modes:

:::note

Incremental sync modes are only available for the User Insights stream.

:::

Supported streams

This connector uses the Instagram Graph API (v23.0) to sync data from Instagram Business and Creator accounts. For Instagram Ads performance data, use the Facebook Marketing source.

You can use these streams:

  • Users: Profile information for each connected Instagram Business or Creator account.
  • User Insights: Daily account-level metrics, including follower_count, reach, and online_followers. This is the only incremental stream. It uses the date field as its cursor.
  • User Lifetime Insights: Demographic breakdowns of followers by city, country, and age/gender.
  • Media: All media objects published by each account, including photos, videos, reels, and carousel albums. For carousel albums, the connector fetches detailed information for each child media item.
  • Media Insights: Engagement metrics for each media item. The requested metrics vary by media type: Reels, Video, Carousel Album, or Image.
  • Stories: Currently published stories. The Instagram API only returns stories that are live during the sync. Expired stories aren’t available.
  • Story Insights: Engagement metrics for currently published stories.

Entity relationship diagram

Limitations and troubleshooting

Rate limits

Instagram limits API requests per hour. When the connector reaches a rate limit, it retries automatically using exponential backoff. See Facebook’s documentation on rate limiting for more information.

Instagram API limitations

  • Data delay: Metrics data from the Instagram API may be delayed by up to 48 hours.
  • Minimum follower count: The follower_count and online_followers metrics require at least 100 followers on the Instagram Business or Creator account.
  • Data retention: The online_followers metric is only available for the last 30 days. User Insights data is available for up to 30 days in the past.
  • Demographic metrics: Demographic metric calculations include only the top 45 entries. They only count viewers for whom Instagram has demographic data.
  • Stories availability: The Instagram API only returns stories that are currently live and haven’t expired. Stories typically expire 24 hours after posting.
  • Carousel children errors: The connector skips unavailable child media items in carousel albums, such as deleted or restricted items. It continues syncing the remaining children and logs a warning for each skipped child.

User Insights in UTC+ timezones

For accounts in UTC+ timezones, the Instagram API returns end_time values at the account’s day boundary, expressed in UTC. The resulting timestamps can be slightly ahead of the current UTC time. The connector applies a one-day lookback window and skips any time slices with future since dates. The next sync picks up these skipped slices.

Troubleshooting

  • Find common Instagram source connector issues on the Airbyte Forum.

IP allow list

If you use Airbyte Cloud and your organisation restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
4.2.512026-11-1091590Update dependencies
4.2.502026-11-0390622Update dependencies
4.2.492026-10-2789921Update dependencies
4.2.482026-10-2089265Update dependencies
4.2.472026-10-1388126Fix user_lifetime_insights dropping the gender dimension of the age,gender breakdown
4.2.462026-10-1388648Update dependencies
4.2.452026-10-0687887Update dependencies
4.2.442026-09-2987211Update dependencies
4.2.432026-09-2286691Update dependencies
4.2.422026-09-1586096Update dependencies
4.2.412026-09-0885526Update dependencies
4.2.402026-08-1884626Update dependencies
4.2.392026-08-1183980Update dependencies
4.2.382026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
4.2.372026-07-281082Roll Cloud back to 4.2.35 — 4.2.36 is built on SDM 7.23.7, which breaks bundled custom components
4.2.362026-07-2882962Update dependencies
4.2.352026-07-2182447Update dependencies
4.2.342026-07-1481881Update dependencies
4.2.332026-06-3081123Update dependencies
4.2.322026-06-2380500Update dependencies
4.2.312026-06-1679913Update dependencies
4.2.302026-06-0978774Update dependencies
4.2.292026-06-0279099Promoted release candidate to GA
4.2.29-rc.22026-05-2678440Add HTTPAPIBudget for rate limit protection
4.2.29-rc.12026-05-2678440Enable progressive rollout for concurrency tuning
4.2.282026-04-2877272Update dependencies
4.2.272026-04-2176627Update dependencies
4.2.262026-04-1376276Rename “concurrent workers” to “concurrent threads” in connector spec
4.2.252026-04-0274721Handle errors when fetching carousel children media to prevent sync failures
4.2.242026-04-0276027Improved error handling for Instagram rate limit responses with descriptive error messages
4.2.232026-03-2475344Update dependencies
4.2.222026-03-1975206Handle Instagram API ‘since param is not valid’ error gracefully for user_insights stream
4.2.212026-03-1274800Add lookback window and filter future-dated records in user_insights to prevent cursor from advancing past current UTC
4.2.202026-03-1074502Update dependencies
4.2.192026-03-0373045Update dependencies
4.2.182026-02-2474006Fix user_insights end_datetime to cover current day for UTC+ accounts
4.2.172026-02-2472266Add views metric and timestamp to media_insights stream
4.2.162026-01-2071966Update dependencies
4.2.152026-01-1471406Update dependencies
4.2.142025-12-1870530Update dependencies
4.2.132025-11-2570157Update dependencies
4.2.122025-11-1869536Update dependencies
4.2.112025-10-2968761Update dependencies
4.2.102025-10-2168506Update dependencies
4.2.92025-10-1467975Update dependencies
4.2.82025-10-0767366Update dependencies
4.2.72025-09-3066800Update dependencies
4.2.62025-09-0966045Update dependencies
4.2.52025-08-2565119Migrate to API v23
4.2.42025-08-2365316Update dependencies
4.2.32025-08-0964640Update dependencies
4.2.22025-08-0264281Update dependencies
4.2.12025-07-1960614Update dependencies
4.2.02025-07-1763358Promoting release candidate 4.2.0-rc.1 to a main version.
4.2.0-rc.12025-07-1662954Migrate to manifest-only format.
4.1.02025-07-1463289Promoting release candidate 4.1.0-rc.3 to a main version.
4.1.0-rc.32025-07-1062902Revert add views metric to StoryInsights and MediaInsights streams.
4.1.0-rc.22025-07-0962844Migrate UserInsights stream to low-code
4.1.0-rc.12025-05-2760848Add views metric to StoryInsights and MediaInsights streams.
4.0.52025-05-1059798Update dependencies
4.0.42025-05-0359243Update dependencies
4.0.32025-04-2658773Update dependencies
4.0.22025-04-1958167Update dependencies
4.0.12025-04-1257704Update dependencies
4.0.02025-04-0755860Remove deprecated metrics from StoryInsights, UserInsights and MediaInsights streams.
3.2.52025-04-0557069Update dependencies
3.2.42025-03-2956666Update dependencies
3.2.32025-03-2256020Update dependencies
3.2.22025-03-1055685Disable cache for InstagramMediaChildrenTransformation
3.2.12025-03-0855463Update dependencies
3.2.02025-02-2854364Update to CDK v6
3.1.92025-03-0154789Update dependencies
3.1.82025-02-2254364Update dependencies
3.1.72025-02-1553846Update dependencies
3.1.62025-02-0853291Update dependencies
3.1.52025-02-0653171Fix missing OAuth fields
3.1.42025-02-0152260Update dependencies
3.1.32025-01-2052035Upgrade to API v21.0
3.1.22025-01-1144223Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
3.1.12025-01-0951018Remove deprecated metrics from StoryInsights and MediaInsights streams.
3.1.02024-07-1341937New metrics added for StoryInsights and MediaInsights streams.
3.0.222024-07-2742721Update dependencies
3.0.212024-07-2042346Update dependencies
3.0.202024-07-1341784Update dependencies
3.0.192024-07-1041586Update dependencies
3.0.182024-07-0941109Update dependencies
3.0.172024-07-0841046Use latest CDK version possible
3.0.162024-07-0640903Update dependencies
3.0.152024-07-0240569Migrate MediaInsights and StoryInsights to low-code
3.0.142024-06-2640524Fix Api stream when the results contain not business accounts
3.0.132024-06-2540456Update dependencies
3.0.122024-06-2439504Migrate Media, Users, UserLifeTimeInsights and Stories to low-code
3.0.112024-06-2240127Update dependencies
3.0.102024-06-0639303[autopull] Upgrade base image to v1.2.2
3.0.92024-05-2138554Upgrade to API v19.0
3.0.82024-05-2038268Replace AirbyteLogger with logging.Logger
3.0.72024-04-1936643Updating to 0.80.0 CDK
3.0.62024-04-1236643Schema descriptions
3.0.52024-03-2036314Unpin CDK version
3.0.42024-03-0735875Remove total_interactions from the MediaInsights queries.
3.0.32024-02-1235177Manage dependencies with Poetry
3.0.22024-01-1534254Prepare for airbyte-lib
3.0.12024-01-0833989Remove metrics from video feed
3.0.02024-01-0533930Upgrade to API v18.0
2.0.12024-01-0333889Change requested metrics for stream media_insights
2.0.02023-11-1732500Add primary keys for UserLifetimeInsights and UserInsights; add airbyte_type to timestamp fields
1.0.162023-11-1732627Fix start_date type; fix docs
1.0.152023-11-1432494Marked start_date as optional; set max retry time to 10 minutes; add suggested streams
1.0.142023-11-1332423Capture media_product_type column in media and stories stream
1.0.132023-11-1032245Add skipping reading MediaInsights stream if an error code 10 is received
1.0.122023-11-0732200The backoff strategy has been updated to make some errors retriable
1.0.112023-08-0329031Reverted advancedAuth spec changes
1.0.102023-08-0128910Updated advancedAuth broken references
1.0.92023-07-0127908Fix bug when user_lifetime_insights stream returns Key Error (end_time), refactored state to use IncrementalMixin
1.0.82023-05-2626767Handle permission error for insights
1.0.72023-05-2626656Remove authSpecification from connector specification in favour of advancedAuth
1.0.62023-03-2826599Handle error for Media posted before business account conversion
1.0.52023-03-2824634Add user-friendly message for no instagram_business_accounts case
1.0.42023-03-1523671Add info about main permissions in spec and doc links in error message to navigate user
1.0.32023-03-1424043Do not emit incomplete records for user_insights stream
1.0.22023-03-1424042Test publish flow
1.0.12023-01-1921602Handle abnormally large state values
1.0.02022-09-2317110Remove custom read function and migrate to per-stream state
0.1.112022-09-0816428Fix requests metrics for Reels media product type
0.1.102022-09-0516340Update to latest version of the CDK (v0.1.81)
0.1.92021-09-306438Annotate Oauth2 flow initialization parameters in connector specification
0.1.82021-08-115354Added check for empty state and fixed tests
0.1.72021-07-194805Add support for previous STATE format
0.1.62021-07-074210Refactor connector to use CDK: - improve error handling - fix sync fail with HTTP status 400 - integrate SAT
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.