Skip to main content

Meta Ads

The meta_ads connector reads objects and insights from the Meta Marketing API: campaigns, ad sets, ads and their delivery metrics. From a job, it can also write: create, update and delete objects, and send server events to the Conversions API.

Install​

sw connectors -i meta_ads

Connect​

Put these keys in a source's auth: block (with provider: meta_ads) or in a job's connection.

KeyWhat it isRequired / default
access_tokenA system-user or long-lived user token (secret)Required
app_idThe app idOptional
app_secretThe app secret. Turns on appsecret_proof verification (secret)Optional
api_versionThe Graph API version, for example v26.0Optional

Secret keys must be secret references ({{ secrets.NAME }}). They are redacted in every log line.

source.yaml
kind: source
name: meta_ads_demo

spec:
config:
account_ids: { type: list, items: string } # ad account ids, without the act_ prefix
start_date: { type: date, default: "-30d" }
secrets:
access_token: { type: string }

auth:
provider: meta_ads
access_token: "{{ secrets.access_token }}"

Read data​

In a source​

streams/insights.yaml
partitions:
- { name: account_id, values: "{{ config.account_ids }}" }
incremental:
cursor_field: date
start: "{{ config.start_date }}"
window: 1d

requests:
- name: raw_insights
operation:
service: AdAccount
method: get_insights
arguments:
id: "act_{{ partition.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]
  • service is a Marketing API object (AdAccount) and method one of its reads (get_insights).
  • The stream reads one day at a time (window: 1d) and runs once per account.
  • Meta sends numbers as text, so cast them in SQL.

In a job, the same operation goes in a call step.

Call arguments​

ArgumentWhat it isRequired / default
idThe object's id. An ad account's id is act_ followed by its number (act_1234567890)Required
fieldsThe fields to read: a list, or comma-separated textOptional
paramsThe call's parameters, for example level and time_range for insightsOptional
is_asynctrue starts an async insights report instead of reading the rows (get_insights only)false

Async insights reports​

For many ad sets or ads, or long date ranges, run insights as an async report. is_async: true on get_insights starts the report and returns its report run (id). The stream then polls the AdReportRun and reads its rows:

streams/ad_set_insights_report.yaml
partitions:
- { name: account_id, values: "{{ config.account_ids }}" }
incremental: { cursor_field: date, start: "{{ config.start_date }}", window: 28d }

requests:
- name: raw_report
async_job:
submit: # 1. start the report
operation:
service: AdAccount
method: get_insights
arguments:
id: "act_{{ partition.account_id }}"
is_async: true
fields: [adset_id, date_start, impressions, clicks, spend]
params:
level: adset
time_increment: 1
time_range: { since: "{{ window.start }}", until: "{{ window.end }}" }
poll: # 2. wait for the report run
operation:
service: AdReportRun
method: api_get
arguments: { id: "{{ submit.id }}", fields: [async_status, async_percent_completion] }
every: 15s
timeout: 1h
done_when: { path: async_status, equals: Job Completed }
fail_when: { path: async_status, in: [Job Failed, Job Skipped] }
results: # 3. read its rows, paged
operation:
service: AdReportRun
method: get_insights
arguments: { id: "{{ submit.id }}", params: { limit: 500 } }

transform:
mode: page
steps:
- name: ad_set_insights
select: |
SELECT record->>'adset_id' AS ad_set_id,
(record->>'date_start')::DATE AS date,
coalesce((record->>'impressions')::BIGINT, 0) AS impressions,
coalesce((record->>'spend')::DOUBLE, 0) AS spend
FROM raw_report

export:
ad_set_insights:
step: ad_set_insights
primary_key: [ad_set_id, date]
  • The poll names its own service (AdReportRun): it reads the report run, not the account.
  • Only reads that can run as a report take is_async. Any other read fails with an error.
  • In a job, the same async_job goes in a call step, with fixed dates from config (call steps have no windows).

Starter streams​

The starter template (examples/sources/ads/meta_ads) has these streams. Copy them and change the fields, the level (ad set, ad) or the SQL to fit your needs.

StreamWhat it readsCall
campaignsCampaign settings, objectives and statusesAdAccount.get_campaigns
ad_setsAd sets, daily budgets and targetingAdAccount.get_ad_sets
campaign_insightsDaily impressions, clicks and spend per campaignAdAccount.get_insights (level: campaign)
ad_set_insights_reportDaily metrics per ad set, from an async reportAdAccount.get_insights (is_async: true)

Write data back​

A job's apply output (reverse ETL) writes to Meta, one object or event per row.

OperationopRows per call
*.create_* (any edge, such as AdAccount.create_campaign)create100, a request per row
*.api_update (any object)update100, a request per row
*.api_delete (needs allow_remove: true)remove100, a request per row
AdsPixel.create_event (the Conversions API)upload1000 in one request
  • Columns are Graph API parameters. Structs and lists are sent as JSON, a text column holding a JSON object is sent as the object, and NULLs are not sent (use nulls: skip_field). Updates and deletes name the object with an id column.
  • Arguments: id is the parent object (act_1234567890), or the pixel for events. params are parameters every row gets (status: PAUSED, test_event_code); a row's own columns win.
  • Results: a rejected row fails alone, with its Graph API code and message; a created object keeps its id. For events, a rejected call fails all its rows.
  • Cut-short calls: updates, deletes and events are sent again (Meta deduplicates events on event_name and event_id). A create_* call is held for you to decide (unknown outcomes).
  • Hash user_data in SQL (sha256(lower(trim(email)))) and cast DECIMAL to DOUBLE.
outputs:
- name: create
connection: meta
step: campaigns # columns: name, objective, status, ...
operation:
service: AdAccount
method: create_campaign
arguments: {id: "act_{{ config.account_id }}"}
apply: {nulls: skip_field, on_row_error: continue}

A campaign needs special_ad_categories (an empty list when none apply), and is_adset_budget_sharing_enabled when it has no budget of its own. Complete jobs (create campaigns and custom conversions, send Conversions API events) are in examples/meta_ads.

Good to know​

  • Engines: sources (streamwright run), and DuckDB and Spark jobs through call steps. Writes run only in job apply outputs.
  • Operations: api_get reads any Marketing API object; get_* reads any of its edges (such as get_insights), paged by the connector. create_*, api_update, api_delete and AdsPixel.create_event write. The installed SDK decides which objects, edges and fields exist; a typo fails before the run with a suggestion.
  • Account-level reads: read entities from the account's edges (AdAccount.get_campaigns, AdAccount.get_ad_sets, AdAccount.get_ads) partitioned by account, rather than from each campaign (one call per campaign). For metrics, one account-level get_insights with level: adset or ad covers every object.
  • Case-sensitive values: Graph API enums are lower case, such as level: adset and date_preset: last_30d.
  • Vendor arguments: fields and params pass through unchanged, for example params: { level: campaign, time_range: { since: '2026-01-01', until: '2026-01-31' } }. Any other argument (such as breakdowns) is added to the request's parameters.
  • Throttling and retries: the connector backs off when Meta's usage headers ask it to. By default it retries Meta's throttling and temporary error codes (4, 17, 613, 80004 and others), errors Meta marks as transient, and HTTP 5xx. Both the error code and subcode are matched. Setting retry: { codes: [17, 613] } on a stream replaces that list.

See also​

  • Apply outputs: how writes are delivered, logged and retried.
  • Call steps: reading from a connector inside a job.
  • Shared vocabulary: run one pipeline across Meta, Google, Microsoft and other ad networks.