Login
Start Trial
Request Demo

Facebook Ads

Knowi connects directly to the Meta (Facebook) Marketing API to pull ad account data, ad performance metrics, and campaign insights into a single analytics platform.

Analyze your Facebook Ads spend, impressions, clicks, conversions, and ROI alongside data from your other sources - no manual CSV exports or spreadsheet wrangling needed.

Overview

Knowi integrates with the Meta Graph API v24.0 (Marketing API) via OAuth. Once connected, you can pull ad accounts, individual ad details, and performance insights with full pagination support.

Connecting

  1. Log in to Knowi and select "Queries" from the left sidebar.

  2. Click on the "New Datasource +" button and select Facebook from the list of datasources.

  3. Click "Connect to Facebook" to authorize Knowi to access your ad account data. You will be redirected to Facebook to approve the connection.

  4. After approving, you'll be redirected back to Knowi. Click "Save" to finish setting up the datasource.

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

Selecting a Page

The Facebook Page Posts and Facebook Post Insights collections read Page-owned data, which Meta serves only against a Page access token - the user token from the OAuth connection is rejected with (#190) ... A Page access token is required for this call for the new Pages experience.

To set this up once, on the datasource (not on each query):

  1. Open the Facebook datasource and click Connect to Facebook (or open a datasource that is already connected).
  2. Pick your Page in the Facebook Page dropdown. It is populated from the Pages your connection manages.
  3. Save. Knowi exchanges that selection for the Page's own access token and stores it with the datasource.

A Page access token minted from a long-lived user token has no expiry, so this is a one-time step. It is invalidated only if you change your Facebook password, revoke the app, or lose your role on the Page - re-authenticate and re-save to refresh it.

Facebook Page is optional: leave it empty for ads-only connections. To report on several Pages, create one datasource per Page.

Collections

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

Ad Account Listing

Retrieves all ad accounts associated with your Facebook user. Use this to find your Account IDs for use with other collections.

Default Cloud9QL:

select data;
select expand(data);

The response includes account IDs and names. Use the account ID (without the act_ prefix) in the Facebook Ads collection.

Facebook Ads

Retrieves ads for a specific ad account, including status, campaign association, and configuration details.

Required Parameters:

  • Facebook Account Id - Your Facebook Ad Account ID (numeric, without the act_ prefix).

Fields returned: account_id, bid_amount, campaign_id, configured_status, name, recommendations, status, adlabels, created_time, conversion_domain, updated_time, adset_id

Default Cloud9QL:

select data;
select expand(data);

Facebook Ads Insight

Retrieves performance metrics for a specific ad, ad set, campaign, or account. This is the most powerful collection for analyzing ad performance.

Required Parameters:

  • Facebook Ads Id - The ID of the ad, ad set, campaign, or account to get insights for.
  • Date - Date preset for the reporting period. Options: today, yesterday, this_month, last_month, this_quarter, maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year.

Optional Parameters:

  • Action Attribution Window - Attribution model for conversions. Options: 1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, dda, default. Default is ["7d_click","1d_view"].
  • Time Increment - Granularity of results. Use all_days for a single aggregated result, monthly for monthly breakdown, or a number 1-90 for N-day periods.
  • Fields - Comma-separated list of metrics to return.

Default Fields:

impressions,reach,ad_name,account_currency,buying_type,campaign_id,campaign_name,clicks,conversion_rate_ranking,conversions,cpc,cpm,ctr,frequency,social_spend,spend,unique_clicks,unique_ctr

Default Cloud9QL:

select data;
select expand(data);

Facebook Page Listing

Lists the Facebook Pages this connection manages, with id, name, category and tasks. Use it to confirm a Page is visible to Knowi.

You do not need to copy anything from here. Post-level reads are Page-owned data and Meta serves them only against a Page access token - but Knowi resolves that token for you: pick the Page in the Facebook Page field on the datasource, and the token is fetched and stored server-side when you save. It never reaches the browser and is never written into a saved query.

Default Cloud9QL:

select data;
select expand(data);

If a Page you manage is missing from this list, re-authenticate the datasource and make sure that Page is ticked in Meta's Page-selection step.

Facebook Page Posts

Retrieves the posts published by a Page, with public engagement counts (reactions, comments, shares).

Required Parameters:

  • None - the Page comes from the datasource's Facebook Page setting (see Selecting a Page above).

Optional Parameters:

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

Fields returned: id, created_time, message, story, permalink_url, status_type, is_published, shares, reactions.summary(total_count), comments.summary(total_count)

Default Cloud9QL:

select data;
select expand(data);

Facebook Post Insights

Retrieves per-post performance metrics for every post on a Page, using the Page Insights API. Insights are expanded inline on the posts edge, so one query returns the posts and their metrics - you do not need to look up individual post ids.

Required Parameters:

  • Metrics - Comma-separated post-level metrics. The Page itself comes from the datasource's Facebook Page setting (see Selecting a Page above).

Optional Parameters:

  • Since / Until - Bounds on created_time.

Default Metrics:

post_media_view,post_total_media_view_unique,post_clicks,post_reactions_by_type_total

Other available metrics: post_clicks_by_type, post_video_views, post_video_views_organic, post_video_views_paid, post_video_views_autoplayed, post_video_views_clicked_to_play, post_video_complete_views_30s_unique.

The impressions metrics no longer exist. Meta removed them in two waves, and a request containing any of them fails outright with (#100) The value must be a valid insights metric - the error names no metric, so it is easy to misread as a permissions or token problem:

Removed metric Removed on Use instead
post_impressions_unique 15 Jun 2025 post_total_media_view_unique
post_impressions 15 Nov 2025 post_media_view
post_impressions_paid, post_impressions_organic 15 Nov 2025 post_media_view with the is_from_ads breakdown
post_impressions_fan 15 Nov 2025 post_media_view with the is_from_followers breakdown

Default Cloud9QL:

select data;
select expand(data);

Use permalink_url to identify a post - message is empty on photo or video posts published without a caption, in which case story carries the auto-generated description.

Metrics arrive nested under each post as insights.data[], so inspect the raw shape with select data; before flattening. A typical flatten:

select data;
select expand(data);
select id, created_time, message, permalink_url, expand(insights.data) as metric;
select id, created_time, message, metric.name as metric_name, metric.values[0].value as value;

Common Use Cases

Track Ad Spend Over Time

select data;
select expand(data);
select date_start, campaign_name, spend, impressions, clicks, ctr
order by date_start desc;

Campaign Performance Comparison

select data;
select expand(data);
select campaign_name, sum(spend) as total_spend, sum(impressions) as total_impressions,
       sum(clicks) as total_clicks, avg(ctr) as avg_ctr
group by campaign_name
order by total_spend desc;

Cost Per Click Analysis

select data;
select expand(data);
select ad_name, spend, clicks, cpc
where clicks > 0
order by cpc asc;

Permissions

Post-level collections need Meta permissions beyond the ad-account ones, so the connector requests:

Permission Needed for
ads_read, business_management Ad Account Listing, Facebook Ads, Facebook Ads Insight
pages_show_list The datasource's Facebook Page picker, and the Facebook Page Listing collection
pages_read_engagement Facebook Page Posts
read_insights Facebook Post Insights

read_insights is an advanced-access permission. Until Meta grants it, Facebook Post Insights returns data only for people who hold a role (admin / developer / tester) on the Meta app, and only for Pages they own - that is Meta's Standard Access tier. Everyone else can still use Facebook Page Listing and Facebook Page Posts, which need only pages_show_list and pages_read_engagement: those give post text, permalinks, and reaction / comment / share counts, but not impressions, reach or engaged users.

If you connected this datasource before post insights were added, re-authenticate it. Existing access tokens were issued without the Page permissions, so the post collections will fail with a permissions error until you reconnect. Open the datasource, click Connect to Facebook again and approve the additional permissions (Meta re-prompts for them), then Save.

When approving, make sure the Pages you want to report on are ticked in Meta's "What Pages do you want to use with Knowi?" step - Pages left unticked will not appear in Facebook Page Listing.

Scheduling

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

Notes

  • Knowi uses Meta Graph API v24.0 (released October 2025).
  • Facebook access tokens obtained via OAuth are long-lived offline tokens.
  • API rate limits are managed automatically by Knowi's pagination engine.
  • You need a Facebook Business account with ad account access to use this connector.
  • For the latest available fields and metrics, refer to the Meta Marketing API documentation.