Meta Ads

The meta_ads connector reads insights and objects from the Meta Marketing API, using the same declarative shape as every StreamWright connector.

Auth

source.yaml

spec:
  config:
    account_id: { type: string }         # act_<id>
  secrets:
    meta_access_token: { type: string }
auth:
  provider: meta_ads
  account_id: "{{ config.account_id }}"
  access_token: "{{ secrets.meta_access_token }}"

Reading data

streams/insights.yaml

requests:
  - name: raw_insights
    sdk: meta_ads
    service: AdAccount
    method: get_insights
    arguments:
      id: "act_{{ config.account_id }}"
      fields: [account_id, campaign_id, campaign_name, date_start, impressions, clicks, spend]
      params:
        level: campaign
        time_increment: 1
        time_range: { since: "{{ window.start }}", until: "{{ window.end }}" }

transform:
  mode: page
  steps:
    - name: insights
      select: |
        SELECT
          record->>'account_id'                         AS account_id,
          record->>'campaign_id'                        AS campaign_id,
          record->>'campaign_name'                      AS campaign_name,
          (record->>'date_start')::DATE                 AS date,
          coalesce((record->>'impressions')::BIGINT, 0) AS impressions,
          coalesce((record->>'clicks')::BIGINT, 0)      AS clicks,
          coalesce((record->>'spend')::DOUBLE, 0)       AS spend
        FROM raw_insights

export:
  insights:
    step: insights
    primary_key: [campaign_id, date]

Reference streams (examples)

The starter template (examples/sources/ads/meta_ads) includes the following reference streams:

Stream	Description	Method / Level
campaigns	Campaign settings, objectives, and statuses	objects (Campaign)
ad_sets	Ad sets, daily budgets, and targeting	objects (AdSet)
campaign_insights	Daily delivery metrics (impressions, clicks, spend)	insights (level: campaign)

Customizable Streams

These streams are reference examples. Because streams in StreamWright are declarative, you can customize fields, query at other breakdown levels (ad, adset), or adjust DuckDB SQL transformations to fit your needs.

Shared vocabulary

meta_ads maps to the same canonical nodes as Google and Microsoft Ads, so a single pipeline runs across every network.

See the connector's folder in the repo for the full option list and exact credential fields.