Instagram

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 ? you must have a linked Instagram Business/Creator account

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.

Endpoint fields: name, instagram_business_account{id,username}.

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. Start with reach.

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);

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 include today, yesterday, this_month, last_month, last_7d, last_30d, last_90d, this_quarter, last_quarter, this_year, last_year, 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.

Common Pitfalls

| Error / symptom | Cause | Fix | |---|---|---| | (#100) Tried accessing nonexisting field (insights) | You used an ad-account id (act_? or its number) as the Instagram Account Id. An ad account has no Instagram insights edge. | Use the instagram_business_account.id from Instagram Accounts. | | (#100) The value must be a valid insights metric | You used the Page id instead of the Instagram account id (a Page has its own insights edge that rejects Instagram metrics), or requested a metric not valid for your account. | Use the instagram_business_account.id, and start with metric=reach. | | Instagram Accounts returns a Page with no instagram_business_account | The Page has no linked Instagram Business/Creator account. | Convert the Instagram account to Business/Creator and link it to the Page, then reconnect. | | Empty result with no error | The account/metric has no data for the period. | Zero/empty results are normal for new or low-activity accounts. |

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.