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.
| Key | What it is | Required / default |
|---|---|---|
access_token | A system-user or long-lived user token (secret) | Required |
app_id | The app id | Optional |
app_secret | The app secret. Turns on appsecret_proof verification (secret) | Optional |
api_version | The Graph API version, for example v26.0 | Optional |
Secret keys must be secret references ({{ secrets.NAME }}). They are redacted in every log line.
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
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]
serviceis a Marketing API object (AdAccount) andmethodone 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
| Argument | What it is | Required / default |
|---|---|---|
id | The object's id. An ad account's id is act_ followed by its number (act_1234567890) | Required |
fields | The fields to read: a list, or comma-separated text | Optional |
params | The call's parameters, for example level and time_range for insights | Optional |
is_async | true 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:
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_jobgoes in a call step, with fixed dates fromconfig(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.
| Stream | What it reads | Call |
|---|---|---|
campaigns | Campaign settings, objectives and statuses | AdAccount.get_campaigns |
ad_sets | Ad sets, daily budgets and targeting | AdAccount.get_ad_sets |
campaign_insights | Daily impressions, clicks and spend per campaign | AdAccount.get_insights (level: campaign) |
ad_set_insights_report | Daily metrics per ad set, from an async report | AdAccount.get_insights (is_async: true) |
Write data back
A job's apply output (reverse ETL) writes to Meta, one object or event per row.
| Operation | op | Rows per call |
|---|---|---|
*.create_* (any edge, such as AdAccount.create_campaign) | create | 100, a request per row |
*.api_update (any object) | update | 100, a request per row |
*.api_delete (needs allow_remove: true) | remove | 100, a request per row |
AdsPixel.create_event (the Conversions API) | upload | 1000 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 anidcolumn. - Arguments:
idis the parent object (act_1234567890), or the pixel for events.paramsare 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_nameandevent_id). Acreate_*call is held for you to decide (unknown outcomes). - Hash
user_datain SQL (sha256(lower(trim(email)))) and castDECIMALtoDOUBLE.
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_getreads any Marketing API object;get_*reads any of its edges (such asget_insights), paged by the connector.create_*,api_update,api_deleteandAdsPixel.create_eventwrite. 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-levelget_insightswithlevel: adsetoradcovers every object. - Case-sensitive values: Graph API enums are lower case, such as
level: adsetanddate_preset: last_30d. - Vendor arguments:
fieldsandparamspass through unchanged, for exampleparams: { level: campaign, time_range: { since: '2026-01-01', until: '2026-01-31' } }. Any other argument (such asbreakdowns) 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,80004and others), errors Meta marks as transient, and HTTP 5xx. Both the error code and subcode are matched. Settingretry: { 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.