Skip to main content

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.

KeyWhat it isRequired / default
typebearerRequired
tokenThe access token (secret: a {{ secrets.NAME }} reference, redacted in every log line)Required

The http block describes the API. The values Apple Ads needs:

KeyValue
base_urlhttps://api.ads.apple.com
headersX-AP-Context: "adAccountId=...", which scopes every request to your ad account
paginatoroffset with in: body, offset_param: pagination.offset, limit_param: pagination.limit, total_path: pagination.totalCount
recordspath: result
source.yaml
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 POST queries. The paginator writes pagination.offset and pagination.limit into the JSON body (in: body) and stops at pagination.totalCount.
  • Records come from the response's result list.

Read data​

In a source​

streams/campaigns.yaml
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:

streams/campaign_reports.yaml
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') }}" and endTime the same way.
  • Impression-share reports are async only in Apple's deprecated Campaign Management API v5: create the report, check it until its state is COMPLETED, then download the CSV at downloadUri. Apple allows up to 10 such reports per 24 hours, each up to 30 days. If you still use them, they fit an async_job with a CSV download.

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.

StreamWhat it readsEndpoint (POST)
campaignsCampaigns and daily budgets/v1/campaigns/query
ad_groupsAd groups and default bids across campaigns/v1/adgroups/query
keywordsKeywords, match types and bid amounts/v1/keywords/query
campaign_reportsImpressions, 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. When json holds {{ 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/query returns every ad group with its campaignId. 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​