Docs / Meta Ads

Connect Meta Ads

Facebook & Instagram ad insights

climpt reads Meta Ads through BigQuery rather than the Marketing API. You set up a Facebook Ads transfer with the BigQuery Data Transfer Service, and climpt queries the resulting dataset read-only. The transfer needs a Meta developer app; climpt does not.

The token expires

Meta transfers authenticate with a long-lived user access token, typically valid for 60 days. When it lapses the transfer stops and the data quietly goes stale, so it is worth a calendar reminder to re-authorize.

What the transfer needs

Meta App ID
The client ID, from your app’s settings in Meta Developers.
Meta App Secret
The client secret, from the same place.
Long-lived access token
Generated during authorization in the Google Cloud console.

Step 1 · Create the transfer

  1. Create a Business-type app in Meta Developers and note its App ID and App Secret.
  2. In the Google Cloud console, open BigQuery → Data transfers → Create transfer and choose Facebook Ads as the source.
  3. Enter the App ID as client ID and the App Secret as client secret.
  4. Copy the redirect URI shown in the transfer form and add it to your Meta app’s OAuth settings. The authorization will fail without this.
  5. Click Authorize, sign in, and let it populate the refresh token field.
  6. Select which ads objects to transfer — start narrow — and set a refresh window, for example seven days.
  7. Choose or create a destination dataset, for example meta_ads_raw, set a schedule and save.
  8. Wait for the first successful run.

What arrives

AdAccounts
Daily snapshots of account state.
AdInsights
Ad insights reports, date-partitioned.
AdInsightsActions
Action breakdowns, date-partitioned.

Step 2 · A service account for the dataset

This is an ordinary BigQuery connection, so it uses the same three read-only roles — two at project level, one on the dataset.

roles/bigquery.jobUser
Project level. Lets climpt create a query job.
roles/bigquery.readSessionUser
Project level. Lets climpt read results through the Storage Read API. Without it, discovery succeeds and every query fails with a bigquery.readsessions.create error.
roles/bigquery.dataViewer
On the ads dataset only — not the whole project.
  1. Go to IAM & Admin → Service Accounts and create one named, say, climpt-bigquery-readonly.
  2. Grant it BigQuery Job User and BigQuery Read Session User at project level.
  3. Open BigQuery, find the dataset, and use Share to grant the service account BigQuery Data Viewer.
  4. Create a JSON key from the account’s Keys tab.
  5. In climpt, add a Google BigQuery connection and paste the whole JSON file.

Querying the export

Table names are stable; which fields are present depends on the breakdowns you selected.

SELECT
  DATE(_PARTITIONTIME) AS day,
  SUM(spend) AS spend
FROM `your-project.meta_ads_raw.AdInsights`
WHERE _PARTITIONTIME >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY day
ORDER BY day DESC;

Worth knowing

  • Filter on _PARTITIONTIME — BigQuery bills on data scanned, and insights tables grow fast.
  • If numbers stop moving, check the transfer’s run history first. An expired token looks exactly like a quiet month.
  • Rotate the service account key roughly every 90 days.