Use this page to set up the Instagram source connector and find reference information.
Prerequisites
- A Meta for Developers account
- An Instagram Business or Creator account connected to a Facebook Page
- 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
- Have a Log into your Airbyte Cloud account.
- Click Sources, then click + New source.
- On the Set up the source page, select Instagram from the Source type dropdown.
- Enter a name for the Instagram connector.
- Click Authenticate your Instagram account.
- Log in and authorise the Instagram account.
- (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.
- Click Set up source.
Airbyte Open Source
- Go to the Airbyte Open Source dashboard.
- Click Sources, then click + New source.
- On the Set up the source page, select Instagram from the Source type dropdown.
- Enter a name for your source.
- 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. - (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.
- 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, andonline_followers. This is the only incremental stream. It uses thedatefield 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_countandonline_followersmetrics require at least 100 followers on the Instagram Business or Creator account. - Data retention: The
online_followersmetric 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
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 4.2.51 | 2026-11-10 | 91590 | Update dependencies |
| 4.2.50 | 2026-11-03 | 90622 | Update dependencies |
| 4.2.49 | 2026-10-27 | 89921 | Update dependencies |
| 4.2.48 | 2026-10-20 | 89265 | Update dependencies |
| 4.2.47 | 2026-10-13 | 88126 | Fix user_lifetime_insights dropping the gender dimension of the age,gender breakdown |
| 4.2.46 | 2026-10-13 | 88648 | Update dependencies |
| 4.2.45 | 2026-10-06 | 87887 | Update dependencies |
| 4.2.44 | 2026-09-29 | 87211 | Update dependencies |
| 4.2.43 | 2026-09-22 | 86691 | Update dependencies |
| 4.2.42 | 2026-09-15 | 86096 | Update dependencies |
| 4.2.41 | 2026-09-08 | 85526 | Update dependencies |
| 4.2.40 | 2026-08-18 | 84626 | Update dependencies |
| 4.2.39 | 2026-08-11 | 83980 | Update dependencies |
| 4.2.38 | 2026-07-28 | 83194 | Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override |
| 4.2.37 | 2026-07-28 | 1082 | Roll Cloud back to 4.2.35 — 4.2.36 is built on SDM 7.23.7, which breaks bundled custom components |
| 4.2.36 | 2026-07-28 | 82962 | Update dependencies |
| 4.2.35 | 2026-07-21 | 82447 | Update dependencies |
| 4.2.34 | 2026-07-14 | 81881 | Update dependencies |
| 4.2.33 | 2026-06-30 | 81123 | Update dependencies |
| 4.2.32 | 2026-06-23 | 80500 | Update dependencies |
| 4.2.31 | 2026-06-16 | 79913 | Update dependencies |
| 4.2.30 | 2026-06-09 | 78774 | Update dependencies |
| 4.2.29 | 2026-06-02 | 79099 | Promoted release candidate to GA |
| 4.2.29-rc.2 | 2026-05-26 | 78440 | Add HTTPAPIBudget for rate limit protection |
| 4.2.29-rc.1 | 2026-05-26 | 78440 | Enable progressive rollout for concurrency tuning |
| 4.2.28 | 2026-04-28 | 77272 | Update dependencies |
| 4.2.27 | 2026-04-21 | 76627 | Update dependencies |
| 4.2.26 | 2026-04-13 | 76276 | Rename “concurrent workers” to “concurrent threads” in connector spec |
| 4.2.25 | 2026-04-02 | 74721 | Handle errors when fetching carousel children media to prevent sync failures |
| 4.2.24 | 2026-04-02 | 76027 | Improved error handling for Instagram rate limit responses with descriptive error messages |
| 4.2.23 | 2026-03-24 | 75344 | Update dependencies |
| 4.2.22 | 2026-03-19 | 75206 | Handle Instagram API ‘since param is not valid’ error gracefully for user_insights stream |
| 4.2.21 | 2026-03-12 | 74800 | Add lookback window and filter future-dated records in user_insights to prevent cursor from advancing past current UTC |
| 4.2.20 | 2026-03-10 | 74502 | Update dependencies |
| 4.2.19 | 2026-03-03 | 73045 | Update dependencies |
| 4.2.18 | 2026-02-24 | 74006 | Fix user_insights end_datetime to cover current day for UTC+ accounts |
| 4.2.17 | 2026-02-24 | 72266 | Add views metric and timestamp to media_insights stream |
| 4.2.16 | 2026-01-20 | 71966 | Update dependencies |
| 4.2.15 | 2026-01-14 | 71406 | Update dependencies |
| 4.2.14 | 2025-12-18 | 70530 | Update dependencies |
| 4.2.13 | 2025-11-25 | 70157 | Update dependencies |
| 4.2.12 | 2025-11-18 | 69536 | Update dependencies |
| 4.2.11 | 2025-10-29 | 68761 | Update dependencies |
| 4.2.10 | 2025-10-21 | 68506 | Update dependencies |
| 4.2.9 | 2025-10-14 | 67975 | Update dependencies |
| 4.2.8 | 2025-10-07 | 67366 | Update dependencies |
| 4.2.7 | 2025-09-30 | 66800 | Update dependencies |
| 4.2.6 | 2025-09-09 | 66045 | Update dependencies |
| 4.2.5 | 2025-08-25 | 65119 | Migrate to API v23 |
| 4.2.4 | 2025-08-23 | 65316 | Update dependencies |
| 4.2.3 | 2025-08-09 | 64640 | Update dependencies |
| 4.2.2 | 2025-08-02 | 64281 | Update dependencies |
| 4.2.1 | 2025-07-19 | 60614 | Update dependencies |
| 4.2.0 | 2025-07-17 | 63358 | Promoting release candidate 4.2.0-rc.1 to a main version. |
| 4.2.0-rc.1 | 2025-07-16 | 62954 | Migrate to manifest-only format. |
| 4.1.0 | 2025-07-14 | 63289 | Promoting release candidate 4.1.0-rc.3 to a main version. |
| 4.1.0-rc.3 | 2025-07-10 | 62902 | Revert add views metric to StoryInsights and MediaInsights streams. |
| 4.1.0-rc.2 | 2025-07-09 | 62844 | Migrate UserInsights stream to low-code |
| 4.1.0-rc.1 | 2025-05-27 | 60848 | Add views metric to StoryInsights and MediaInsights streams. |
| 4.0.5 | 2025-05-10 | 59798 | Update dependencies |
| 4.0.4 | 2025-05-03 | 59243 | Update dependencies |
| 4.0.3 | 2025-04-26 | 58773 | Update dependencies |
| 4.0.2 | 2025-04-19 | 58167 | Update dependencies |
| 4.0.1 | 2025-04-12 | 57704 | Update dependencies |
| 4.0.0 | 2025-04-07 | 55860 | Remove deprecated metrics from StoryInsights, UserInsights and MediaInsights streams. |
| 3.2.5 | 2025-04-05 | 57069 | Update dependencies |
| 3.2.4 | 2025-03-29 | 56666 | Update dependencies |
| 3.2.3 | 2025-03-22 | 56020 | Update dependencies |
| 3.2.2 | 2025-03-10 | 55685 | Disable cache for InstagramMediaChildrenTransformation |
| 3.2.1 | 2025-03-08 | 55463 | Update dependencies |
| 3.2.0 | 2025-02-28 | 54364 | Update to CDK v6 |
| 3.1.9 | 2025-03-01 | 54789 | Update dependencies |
| 3.1.8 | 2025-02-22 | 54364 | Update dependencies |
| 3.1.7 | 2025-02-15 | 53846 | Update dependencies |
| 3.1.6 | 2025-02-08 | 53291 | Update dependencies |
| 3.1.5 | 2025-02-06 | 53171 | Fix missing OAuth fields |
| 3.1.4 | 2025-02-01 | 52260 | Update dependencies |
| 3.1.3 | 2025-01-20 | 52035 | Upgrade to API v21.0 |
| 3.1.2 | 2025-01-11 | 44223 | Starting 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.1 | 2025-01-09 | 51018 | Remove deprecated metrics from StoryInsights and MediaInsights streams. |
| 3.1.0 | 2024-07-13 | 41937 | New metrics added for StoryInsights and MediaInsights streams. |
| 3.0.22 | 2024-07-27 | 42721 | Update dependencies |
| 3.0.21 | 2024-07-20 | 42346 | Update dependencies |
| 3.0.20 | 2024-07-13 | 41784 | Update dependencies |
| 3.0.19 | 2024-07-10 | 41586 | Update dependencies |
| 3.0.18 | 2024-07-09 | 41109 | Update dependencies |
| 3.0.17 | 2024-07-08 | 41046 | Use latest CDK version possible |
| 3.0.16 | 2024-07-06 | 40903 | Update dependencies |
| 3.0.15 | 2024-07-02 | 40569 | Migrate MediaInsights and StoryInsights to low-code |
| 3.0.14 | 2024-06-26 | 40524 | Fix Api stream when the results contain not business accounts |
| 3.0.13 | 2024-06-25 | 40456 | Update dependencies |
| 3.0.12 | 2024-06-24 | 39504 | Migrate Media, Users, UserLifeTimeInsights and Stories to low-code |
| 3.0.11 | 2024-06-22 | 40127 | Update dependencies |
| 3.0.10 | 2024-06-06 | 39303 | [autopull] Upgrade base image to v1.2.2 |
| 3.0.9 | 2024-05-21 | 38554 | Upgrade to API v19.0 |
| 3.0.8 | 2024-05-20 | 38268 | Replace AirbyteLogger with logging.Logger |
| 3.0.7 | 2024-04-19 | 36643 | Updating to 0.80.0 CDK |
| 3.0.6 | 2024-04-12 | 36643 | Schema descriptions |
| 3.0.5 | 2024-03-20 | 36314 | Unpin CDK version |
| 3.0.4 | 2024-03-07 | 35875 | Remove total_interactions from the MediaInsights queries. |
| 3.0.3 | 2024-02-12 | 35177 | Manage dependencies with Poetry |
| 3.0.2 | 2024-01-15 | 34254 | Prepare for airbyte-lib |
| 3.0.1 | 2024-01-08 | 33989 | Remove metrics from video feed |
| 3.0.0 | 2024-01-05 | 33930 | Upgrade to API v18.0 |
| 2.0.1 | 2024-01-03 | 33889 | Change requested metrics for stream media_insights |
| 2.0.0 | 2023-11-17 | 32500 | Add primary keys for UserLifetimeInsights and UserInsights; add airbyte_type to timestamp fields |
| 1.0.16 | 2023-11-17 | 32627 | Fix start_date type; fix docs |
| 1.0.15 | 2023-11-14 | 32494 | Marked start_date as optional; set max retry time to 10 minutes; add suggested streams |
| 1.0.14 | 2023-11-13 | 32423 | Capture media_product_type column in media and stories stream |
| 1.0.13 | 2023-11-10 | 32245 | Add skipping reading MediaInsights stream if an error code 10 is received |
| 1.0.12 | 2023-11-07 | 32200 | The backoff strategy has been updated to make some errors retriable |
| 1.0.11 | 2023-08-03 | 29031 | Reverted advancedAuth spec changes |
| 1.0.10 | 2023-08-01 | 28910 | Updated advancedAuth broken references |
| 1.0.9 | 2023-07-01 | 27908 | Fix bug when user_lifetime_insights stream returns Key Error (end_time), refactored state to use IncrementalMixin |
| 1.0.8 | 2023-05-26 | 26767 | Handle permission error for insights |
| 1.0.7 | 2023-05-26 | 26656 | Remove authSpecification from connector specification in favour of advancedAuth |
| 1.0.6 | 2023-03-28 | 26599 | Handle error for Media posted before business account conversion |
| 1.0.5 | 2023-03-28 | 24634 | Add user-friendly message for no instagram_business_accounts case |
| 1.0.4 | 2023-03-15 | 23671 | Add info about main permissions in spec and doc links in error message to navigate user |
| 1.0.3 | 2023-03-14 | 24043 | Do not emit incomplete records for user_insights stream |
| 1.0.2 | 2023-03-14 | 24042 | Test publish flow |
| 1.0.1 | 2023-01-19 | 21602 | Handle abnormally large state values |
| 1.0.0 | 2022-09-23 | 17110 | Remove custom read function and migrate to per-stream state |
| 0.1.11 | 2022-09-08 | 16428 | Fix requests metrics for Reels media product type |
| 0.1.10 | 2022-09-05 | 16340 | Update to latest version of the CDK (v0.1.81) |
| 0.1.9 | 2021-09-30 | 6438 | Annotate Oauth2 flow initialization parameters in connector specification |
| 0.1.8 | 2021-08-11 | 5354 | Added check for empty state and fixed tests |
| 0.1.7 | 2021-07-19 | 4805 | Add support for previous STATE format |
| 0.1.6 | 2021-07-07 | 4210 | Refactor connector to use CDK: - improve error handling - fix sync fail with HTTP status 400 - integrate SAT |