Apple Ads
The apple_ads connector reads campaigns, ad groups, targeting keywords and performance reports from the Apple
Ads Platform API. From a job, it can also send rows to any endpoint. It is a REST connector: you declare the
requests in YAML, the same way as the REST API connector.
Install
sw connectors -i apple_ads
Connect
Apple Ads signs in with an OAuth bearer token. Put these keys in a source's auth: block (with
provider: apple_ads) or in a job's connection.
| Key | What it is | Required / default |
|---|---|---|
type | bearer | Required |
token | The access token (secret: a {{ secrets.NAME }} reference, redacted in every log line) | Required |
The http block describes the API. The values Apple Ads needs:
| Key | Value |
|---|---|
base_url | https://api.ads.apple.com |
headers | X-AP-Context: "adAccountId=...", which scopes every request to your ad account |
paginator | offset with in: body, offset_param: pagination.offset, limit_param: pagination.limit, total_path: pagination.totalCount |
records | path: result |
kind: source
name: apple_ads_demo
spec:
config:
ad_account_id: { type: string, description: "Apple Ads ad account ID (sent as X-AP-Context)" }
secrets:
apple_ads_token: { type: string }
auth:
provider: apple_ads
type: bearer
token: "{{ secrets.apple_ads_token }}"
http:
base_url: https://api.ads.apple.com
headers:
X-AP-Context: "adAccountId={{ config.ad_account_id }}"
paginator:
type: offset
in: body
offset_param: pagination.offset
limit_param: pagination.limit
page_size: 100
total_path: pagination.totalCount
records:
path: result
- Apple Ads reads are
POSTqueries. The paginator writespagination.offsetandpagination.limitinto the JSON body (in: body) and stops atpagination.totalCount. - Records come from the response's
resultlist.
Read data
In a source
description: Apple Ads campaigns and budget configurations.
requests:
- name: raw_campaigns
operation:
path: /v1/campaigns/query
method: POST
json:
pagination:
pageSize: 100
fetchTotalCount: true
transform:
mode: page
steps:
- name: campaigns
select: |
SELECT (record->>'adAccountId')::BIGINT AS ad_account_id,
(record->>'id')::BIGINT AS campaign_id,
record->>'name' AS campaign_name,
record->>'status' AS status,
record->>'servingStatus' AS serving_status,
(record->>'$.dailyBudgetAmount.amount')::DOUBLE AS daily_budget,
record->>'$.dailyBudgetAmount.currency' AS currency,
record->>'startTime' AS start_time,
record->>'endTime' AS end_time
FROM raw_campaigns
export:
campaigns:
step: campaigns
primary_key: [campaign_id]
In a job
The connection holds the sign-in and the http defaults. A step's operation is the same request as in a stream,
and its sql reads the table records (call steps).
connections:
apple_ads_api:
provider: apple_ads
type: bearer
token: "{{ secrets.apple_ads_token }}"
http:
base_url: https://api.ads.apple.com
headers:
X-AP-Context: "adAccountId={{ config.ad_account_id }}"
steps:
- name: campaigns
connection: apple_ads_api
operation:
path: /v1/campaigns/query
method: POST
json: {pagination: {pageSize: 100, fetchTotalCount: true}}
records: {path: result}
paginator: {type: offset, in: body, offset_param: pagination.offset, limit_param: pagination.limit,
page_size: 100, total_path: pagination.totalCount}
sql: |
SELECT (record->>'id')::BIGINT AS campaign_id,
record->>'name' AS campaign_name,
record->>'status' AS status,
(record->>'$.dailyBudgetAmount.amount')::DOUBLE AS daily_budget
FROM records
Reports
Reports are synchronous queries: a report request returns its rows at once, so it is a normal request, not an
async report. Report endpoints return rows under result.rows, so the request
overrides records.path:
description: Apple Ads campaign reporting analytics (impressions, taps, installs, spend).
requests:
- name: raw_campaign_reports
operation:
path: /v1/reports/apps/campaigns/query
method: POST
json:
pagination:
pageSize: 100
fetchTotalCount: true
timeRange:
startTime: "2026-01-01"
endTime: "2026-01-07"
granularity: DAILY
records:
path: result.rows
transform:
mode: page
steps:
- name: campaign_reports
select: |
SELECT COALESCE(record->'metadata'->>'id', record->>'campaignId')::BIGINT AS campaign_id,
record->'metadata'->>'name' AS campaign_name,
COALESCE((record->'totalMetrics'->>'impressions')::BIGINT, (record->>'impressions')::BIGINT) AS impressions,
COALESCE((record->'totalMetrics'->>'taps')::BIGINT, (record->>'taps')::BIGINT) AS taps,
COALESCE((record->'totalMetrics'->>'totalInstalls')::BIGINT, (record->>'installs')::BIGINT) AS installs,
COALESCE((record->'totalMetrics'->'localSpend'->>'amount')::DOUBLE, (record->>'$.localSpend.amount')::DOUBLE) AS spend
FROM raw_campaign_reports
export:
campaign_reports:
step: campaign_reports
primary_key: [campaign_id]
- To read by date window, make the stream incremental and set
startTime: "{{ window.start | date('%Y-%m-%d') }}"andendTimethe same way. - Impression-share reports are async only in Apple's deprecated Campaign Management API v5: create the report, check
it until its
stateisCOMPLETED, then download the CSV atdownloadUri. Apple allows up to 10 such reports per 24 hours, each up to 30 days. If you still use them, they fit anasync_jobwith a CSVdownload.
Starter streams
The starter template
(examples/sources/ads/apple_ads)
has these streams. Its source.yaml also takes an optional campaign_ids list for the child streams. Copy them and
change the columns, SQL or endpoints to fit your needs.
| Stream | What it reads | Endpoint (POST) |
|---|---|---|
campaigns | Campaigns and daily budgets | /v1/campaigns/query |
ad_groups | Ad groups and default bids across campaigns | /v1/adgroups/query |
keywords | Keywords, match types and bid amounts | /v1/keywords/query |
campaign_reports | Impressions, taps, installs and spend | /v1/reports/apps/campaigns/query |
Write data back
A job's apply output (reverse ETL) sends rows to any endpoint of this API as HTTP requests:
outputs:
- name: send
connection: apple_ads_api
step: rows # each row becomes one request's JSON body
operation:
path: /endpoint # the API endpoint that takes the rows
method: POST
apply:
on_row_error: continue
- Without
json, each row is sent as one request, with the row as its JSON body. Whenjsonholds{{ rows }}, the whole chunk goes in one request. {{ row.<column> }}puts a row's value in the path or body (/campaigns/{{ row.id }}).- A row the API rejects fails alone, with the HTTP status as its code.
- Check Apple's API reference for the endpoint and the fields it expects.
Good to know
- Engines: sources (
streamwright run), and DuckDB and Spark jobs through call steps. Writes run only in job apply outputs. - Retries: a request is retried on HTTP 429, 500, 502, 503 and 504 by default (REST API).
- Query across campaigns:
/v1/adgroups/queryreturns every ad group with itscampaignId. Prefer it to one request per campaign. - Case-sensitive values: enums are upper case, such as
granularity: DAILY. - Vendor arguments: any HTTP request field goes to Apple unchanged, for example a request
selector: { orderBy: [...] }.
See also
- REST API connector: paginators and request keys in full.
- Apply outputs: how rows are sent to a REST API.