Linking Instagram as a source

Let AI connect your sources for you

Skip the manual setup — run this in your project and the wizard auto-detects your databases and APIs and connects them to PostHog.

Learn more

Alpha release

This source is currently in alpha. The interface and available tables may change.

The Instagram connector syncs an Instagram professional account into PostHog: the profile, its posts, stories and comments, and the insights Meta reports for the account and for each post. You can then analyze social activity alongside your product data.

Prerequisites

An Instagram professional account, either Business or Creator. Personal accounts aren't supported.
A Facebook page linked to that professional account. PostHog reads the account through its page, using Instagram API with Facebook Login.
A Facebook account with access to that page.

Adding a data source

In PostHog, go to the Sources tab of the data pipeline section.
Click + New source and click Link next to this source.
Enter your credentials (see Configuration below) and click Next.
Select the tables you want to sync, choose a sync method and frequency, then click Import.

Once the syncs are complete, you can start querying this data in PostHog.

When linking Instagram, you'll need:

Instagram account: connect your account and sign in with Facebook. Grant access to the page your professional account is linked to, along with Instagram insights and comments. PostHog asks for the instagram_basic, instagram_manage_insights, instagram_manage_comments, pages_show_list, and pages_read_engagement permissions.
Instagram professional account: pick the account you want to sync. PostHog lists the professional accounts on the pages you granted access to.
Start date (optional): the earliest date to sync posts and account insights from, in YYYY-MM-DD format. Leave it empty to sync every post and the last 90 days of account insights.

Sync modes

Each table can be synced in one of several modes, depending on what the source supports:

Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
Incremental – only new or updated rows are synced on each run, using a cursor field (such as an updated_at timestamp). Cheaper than a full refresh, but deletes aren't captured.
Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.

See sync methods for a full explanation of how each mode works and how to choose between them.

Two tables sync incrementally:

media uses each post's creation time, so a run fetches only posts created since the previous run.
account_insights uses the metric's date and continues from the last day it synced.

The rest have no time filter on Meta's side, so they do a full refresh on every run.

Instagram deletes stories after 24 hours. The stories table only holds stories that were live when a sync ran, so sync at least daily to build up a history.

Configuration

Option	Type	Required
`Instagram account`	oauth	Yes
`Instagram professional account`	oauth-account-select	Yes
`Start date`	text	No

Supported tables

Table	Description	Sync method	Incremental field	Primary key
`account`	The connected Instagram professional account, refreshed on every sync.	Full refresh	—	—
`media`	Posts, reels and carousels published by the account, newest first. Limited to the 10,000 most recently created media.	Incremental, Full refresh	timestamp	—
`stories`	Stories published by the account in the last 24 hours. Instagram deletes stories after 24 hours, so history only accumulates from syncs that ran while a story was live.	Full refresh	—	—
`media_comments`	Comments on the account's media, one row per comment. Keyed by media and comment, because the table aggregates comments across every post.	Full refresh	—	—
`media_insights`	Lifetime performance metrics per post, in long format: one row per media and metric. Available metrics vary by media type, and Meta retires metrics between Graph API versions.	Full refresh	—	—
`account_insights`	Daily account-level metrics, in long format: one row per metric and day. Meta only serves insights in windows of at most 30 days and retains roughly two years of history.	Incremental, Full refresh	date	—

Limitations

Meta returns at most the 10,000 most recently created posts, so media and the tables built from it cover that window.
Account insights go back about two years. An earlier start date is clamped to that limit.
media_insights and account_insights are in long format: one row per metric, not one column per metric. The metrics Meta returns vary by media type, and Meta retires metrics between Graph API versions.

Troubleshooting

No accounts to pick from: the Facebook account you connected has no Instagram professional account on the pages you granted. Check that the account is Business or Creator, that it's linked to a page, and that you granted access to that page.
"The Instagram connection has expired": Meta access tokens expire, and revoking PostHog's access in Facebook ends the connection early. Reconnect the Instagram account in the source's settings, then re-sync.
"The Instagram connection is missing permissions this sync needs": the grant left out one of the permissions listed above. Reconnect the account and accept access to the page, insights, and comments.
Empty insights tables: Meta reports insights only for professional accounts, and only for days the account was active. Compare the same metrics in the Instagram app before treating this as a sync problem.

If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.