Knowi connects to the Meta Graph API to pull Instagram Business/Creator account insights - reach, views, engagement, follower activity - into a single analytics platform, alongside data from your other sources.

Overview

Knowi integrates with the Meta Graph API v24.0 via OAuth. Instagram insights are accessed through the Facebook Page that your Instagram account is linked to, so the connector also exposes the related ad-account collections.

Prerequisite

Instagram insights are only available for an Instagram Business or Creator account that is linked to a Facebook Page you manage. Before connecting, make sure:

1. Your Instagram account is converted to a Business or Creator account (Instagram app > Settings > Account type and tools).
2. That Instagram account is linked to a Facebook Page you administer (Facebook Page > Settings > Linked accounts > Instagram).

If your Page has no linked Instagram Business/Creator account, the Instagram Accounts collection will return the Page with no instagram_business_account field, and insights cannot be retrieved. A personal Instagram account will not work.

Connecting

1. Log in to Knowi and select "Queries" from the left sidebar.
2. Click on the "New Datasource +" button and select Instagram from the list of datasources.
3. Click "Authenticate" to authorize Knowi. You will be redirected to Facebook to approve the connection (Instagram insights are served through the Meta Graph API).
4. After approving, you'll be redirected back to Knowi. Click "Save" to finish setting up the datasource.

Note: Meta access tokens are long-lived and do not require periodic refresh. However, if you change your password or revoke app permissions, you will need to reconnect.

Collections

After connecting, select a collection from the dropdown to query your data.

Instagram Accounts

Run this first. It lists the Facebook Pages you manage and, for each, the linked Instagram Business/Creator account. You need the Instagram account id from here for the Instagram User Insights collection.

Fields returned: name, instagram_business_account, connected_instagram_account

Default Cloud9QL:

select data;

Look at the raw data for each Page. You are looking for the nested block:

"instagram_business_account":  { "id": "17841..." },
"connected_instagram_account": { "id": "17841..." }

• The Instagram account id is the instagram_business_account.id - a ~17-digit number (often starting with 17841). This is not the Page id (the top-level id) and not your ad-account id (act_...).
• connected_instagram_account.id is usually the same value and serves as a fallback if instagram_business_account is absent.
• If a Page has neither block, that Page has no linked Instagram Business/Creator account - see the Prerequisite section above.

Tip: keep the query as select data; (raw JSON) to read the nested instagram_business_account.id. The select expand(data); shortcut only surfaces the top-level Page name and id, so the nested Instagram id will not appear as a column.

Instagram User Insights

Retrieves insight metrics for a specific Instagram Business/Creator account.

Required Parameters:

• Instagram Account Id - The instagram_business_account.id from the Instagram Accounts collection (NOT the Page id, NOT the act_... ad-account id).
• Metrics - Comma-separated metric list. Defaults to reach,follows_and_unfollows. Start with reach on its own if a metric errors.

Metrics notes:

• Start with reach - it is the most reliable and works with the connector's fixed period=day, metric_type=total_value settings.
• impressions is deprecated on the current Graph API - use views instead.
• Some metrics (e.g. follower demographics) require the account to have 100+ followers or they return an error.
• Available metrics include: reach, views, accounts_engaged, total_interactions, likes, comments, shares, saves, replies, follows_and_unfollows, profile_links_taps. Request them one or two at a time first to confirm each is valid for your account before combining.

Default Cloud9QL:

select data;
select expand(data);

Instagram Media

Lists the posts (media) on an Instagram Business/Creator account with their public like and comment counts. Use it to see what is on the account, or to grab a media id.

Required Parameters:

• Instagram Account Id - The instagram_business_account.id from the Instagram Accounts collection.

Optional Parameters:

• Since / Until - Bounds on the post timestamp. Accepts YYYY-MM-DD or a unix timestamp; Knowi date tokens such as {$c9_today-30d:epoch} also work.

Fields returned: id, caption, media_type, media_product_type, permalink, timestamp, like_count, comments_count

Default Cloud9QL:

select data;
select expand(data);

Instagram Post Insights

Retrieves per-post (media-level) insight metrics for every post on the account. Insights are expanded inline on the media edge, so one query returns the posts and their metrics - you do not need individual media ids.

Required Parameters:

• Instagram Account Id - The instagram_business_account.id from the Instagram Accounts collection (NOT the Page id, NOT the act_... ad-account id).
• Metrics - Comma-separated media-level metrics.

Optional Parameters:

• Since / Until - Bounds on the post timestamp.

Default Metrics:

reach,total_views,likes,comments,shares,saved

Metrics notes:

• Media-level metric names differ from the account-level ones used by Instagram User Insights: the media metric is saved (singular, past tense) while the account metric is saves.
• impressions is deprecated for media created on or after 2 July 2024 - use total_views.
• Meta still lists views and total_interactions as in development, so they are deliberately not in the default set. Add them only after confirming they return data for your account.
• Availability varies by media_product_type:

• A metric that is not valid for one media type fails the whole call with (#100) ... is not valid for this media. Drop the offending metric (start from reach alone to confirm the account works) or narrow the date range so the result set holds a single media type.

Default Cloud9QL:

select data;
select expand(data);

Metrics arrive nested under each post as insights.data[]. A typical flatten:

select data;
select expand(data);
select id, timestamp, media_type, permalink, expand(insights.data) as metric;
select id, timestamp, media_type, metric.name as metric_name, metric.values[0].value as value;

Ad Accounts

Lists the ad accounts associated with your Meta user. Useful if you also want to analyze Instagram-placement ad performance.

Default Cloud9QL:

select data;
select expand(data);

Ad Campaign Analytics

Retrieves campaign-level performance (reach, impressions, clicks, spend) for an ad account, aggregated per campaign via the Marketing API /insights edge.

Required Parameters:

• Ad Account Id - The numeric ad-account id, without the act_ prefix (e.g. 672194280184956). Use the account_id from the Ad Accounts collection.

Optional Parameters:

• Date - Reporting period (default last_30d). Options: today, yesterday, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, maximum.

Default Cloud9QL:

select data;
select expand(data);

Typical Flow

1. Run Instagram Accounts with select data; -> copy the instagram_business_account.id.
2. Open Instagram User Insights -> paste that id into Instagram Account Id -> set Metrics to reach -> run.
3. Add more metrics (e.g. views, accounts_engaged) once the basic call succeeds.
4. For per-post numbers, open Instagram Post Insights -> paste the same id into Instagram Account Id -> run with the default metrics, trimming any that error.

Common Pitfalls

Permissions

Post-level (media) insights use the same permissions the connector already requests: instagram_basic and instagram_manage_insights (plus pages_show_list and pages_read_engagement to reach the Instagram account through its linked Page).

If you connected this datasource before post insights were added, re-authenticate it if the post collections return a permissions error - and make sure the Facebook Page linked to your Instagram account is ticked in Meta's Page-selection step during approval.

Scheduling

Once configured, schedule your queries to run automatically (e.g., daily) to keep dashboards current. Knowi handles cursor-based pagination automatically through Meta's paging.next URL.

Notes

• Knowi uses Meta Graph API v24.0.
• Instagram insights require a Business or Creator account linked to a Facebook Page you manage.
• Meta access tokens obtained via OAuth are long-lived offline tokens.
• For the latest available metrics, refer to the Instagram Platform / Insights documentation.