Skip to main content

Apple Ads (Apple Search Ads)

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Connector type
Available Data replicationNot available Agent(learn more)
Support Level
Marketplace
Connector Version
1.1.22 (last updated 4 days ago)
Sync Success Rate
Medium
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
e59c8416-c2fa-4bd3-9e95-52677ea281c1

This page contains the setup guide and reference information for the Apple Ads source connector.

warning

Apple has deprecated the Apple Ads Campaign Management API that this connector uses and plans to sunset it on January 26, 2027. Apple recommends the Apple Ads Platform API as its replacement. This connector still calls Campaign Management API v5.

Prerequisites​

  • An Apple Ads account with an administrator who can invite users with API permissions.
  • Your Apple Ads organization id (orgId), shown in the Apple Ads UI. Each Airbyte source syncs data for a single orgId.
  • An Apple Ads API user with an OAuth client ID and a client secret (see Step 1 below).
  • OpenSSL and a script or library that can sign an ES256 JSON Web Token (JWT). Apple's OAuth guide includes a Python example.

Setup guide​

Step 1: Create an API user and OAuth credentials in Apple Ads​

The connector authenticates to the Apple Ads Campaign Management API with the OAuth 2 client credentials grant. Apple gives you a client ID when you upload a public key. The client secret is a JWT that you create and sign yourself with the matching private key. Apple's full guide is at Implementing OAuth for the Apple Ads API. The steps are:

  1. Sign in to Apple Ads as an account administrator, select the account from the Users menu, and go to Account Settings → User Management.

  2. Click Invite Users. In User Access and Role, select an API role, such as API Account Manager or API Account Read Only, and send the invite. The invited user activates the account from the invitation email.

  3. As the API user, generate a private key and extract its public key:

    openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
    openssl ec -in private-key.pem -pubout -out public-key.pem

  4. In Apple Ads, go to Account Settings → API, paste the contents of public-key.pem into Public Key, and click Save. Apple then shows your clientId, teamId, and keyId.

  5. Create the client secret: a JWT signed with private-key.pem using the ES256 algorithm, with these values:

    • Header: alg is ES256 and kid is your keyId.
    • Payload: sub is your clientId, iss is your teamId, aud is https://appleid.apple.com, iat is the current UNIX timestamp, and exp is a UNIX timestamp less than 180 days after iat.

    The encoded JWT is the value for Client Secret in Airbyte. Keep the private key secure; you need it every time you create a new client secret.

note

Apple accepts a client secret for at most 180 days. Before your client secret expires, create a new one and update the Client Secret field of the source. Otherwise, syncs fail with a 401 error.

Step 2: Set up the source connector in Airbyte​

  1. In Airbyte, click Sources and then click + New source.
  2. Select Apple Ads from the Source type dropdown and enter a name for the source.
  3. For Org Id, enter the orgId of your Apple Ads organization (found in the Apple Ads UI).
  4. For Client Id, enter the clientId from Step 1. For Client Secret, enter the signed JWT you created in Step 1.
  5. For Start Date and End Date, enter dates in YYYY-MM-DD format. Start Date is required. If End Date is blank, Airbyte syncs up to today. Apple serves daily reports for the last 90 days only (ReportingRequest), so set Start Date within that window. If Start Date is earlier, the report streams fail with a configuration error.
  6. For Time Zone, select either UTC (Coordinated Universal Time) or ORTZ (Organization Time Zone). The default is UTC.
  7. For Lookback Window, enter a value between 1 and 30. Apple Ads applies a 30-day attribution window, so the default of 30 ensures late-attributed conversions are captured on each incremental sync. Lower values shorten incremental syncs but may miss late attributions.
  8. (Optional) For Number of Workers, enter a value between 1 and 20 (default 2). This controls how many partitions (campaigns or ad groups) the connector fetches in parallel. Increase it for accounts with many campaigns or ad groups to shorten sync time, at the cost of higher API request volume.
  9. Click Set up source.

The Exponential Backoff Factor and Token Refresh Endpoint fields are hidden in the UI. Set them through the API if you need to: see backoff_factor and token_refresh_endpoint in the parameter table below.

Supported sync modes​

The Apple Ads source connector supports the following sync modes:

The object streams (campaigns, adgroups, keywords, and ads) support full refresh only. The daily report streams also support incremental syncs, using date as the cursor.

Supported streams​

The Apple Ads source connector exposes the following streams. For full schema and field details, see the Apple Ads API reference.

Object streams​

  • campaigns — all campaigns in the organization.
  • adgroups — ad groups across all campaigns.
  • keywords — targeting keywords across all ad groups.
  • ads — ads across all ad groups.

Daily report streams​

The connector requests daily reports from Apple's Reports API, grouped by countryOrRegion. Apple supports hourly, daily, weekly, and monthly granularity, but this connector only requests daily.

note

Report streams use date as the cursor field and declare no primary key. Each row is broken out by countryOrRegion, which the connector exposes as countryorregion. To deduplicate, use the entity ID (campaignId, adGroupId, keywordId or adId), date and countryorregion in the destination.

When Apple reports that a campaign doesn't contain keywords, keywords_report_daily skips that campaign instead of failing the sync.

Performance considerations​

  • Apple access tokens last one hour. When Apple returns 401 Unauthorized, the connector requests a new access token and retries the request.
  • Apple's API enforces rate limits and recommends exponential retry. The connector retries 429 rate-limit responses and 500, 502, 503 and 504 server errors with exponential backoff. The API-only backoff_factor sets the delay multiplier for the report streams.
  • For accounts with many campaigns or ad groups, increase Number of Workers to fetch partitions in parallel and reduce sync time.
  • Apple Ads applies a 30-day attribution window. Reducing Lookback Window below 30 days shortens incremental syncs but may miss late conversions.

Troubleshooting​

  • Apple Ads rejected the credentials (401) even after refreshing the access token: The client secret has expired, or the API user lost access. Create a new client secret as described in Step 1 and update the Client Secret field.
  • Apple Ads denied access (403) for org ...: The API user doesn't have an API role on the organization in Org Id. Ask an account administrator to assign an API role, such as API Account Manager or API Account Read Only, to the API user for that organization.
  • Apple Ads rejected the report request (400): A report stream requested a date that Apple no longer serves. Apple serves daily reports for the last 90 days only. Set Start Date within the last 90 days. If a report stream hasn't synced for longer than that, its saved cursor is also outside the window, so refresh the stream.
  • Apple Ads returned 404 for ...: A campaign or ad group was probably deleted while the sync was running. Run the sync again.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

This connector uses the Apple Ads Campaign Management API v5. Airbyte calls https://api.searchads.apple.com/api/v5 and sends the selected Apple Ads organization in the X-AP-Context header as orgId={orgId}.

For programmatic configuration, use these parameter names:

FieldRequiredDescription
org_idYesApple Ads organization ID to sync.
client_idYesOAuth client ID for the Apple Ads API user.
client_secretYesOAuth client secret for the Apple Ads API user.
start_dateYesEarliest report date to sync, in YYYY-MM-DD format.
end_dateNoLatest report date to sync, in YYYY-MM-DD format. If omitted, Airbyte syncs through the current date.
timezoneNoReporting time zone. Valid values are UTC and ORTZ; defaults to UTC.
lookback_windowNoNumber of days to sync again on incremental report streams. Valid values are 1 through 30. Defaults to 30.
backoff_factorNoExponential retry delay factor for temporary Apple Ads API errors on the report streams. Valid values are 1 through 20. Defaults to 5. Hidden in the UI.
token_refresh_endpointNoOAuth token endpoint. Defaults to Apple's token endpoint with the client_credentials grant and searchadsorg scope. Hidden in the UI.
num_workersNoNumber of concurrent workers for partitioned streams. Valid values are 1 through 20. Defaults to 2.

Reference​

Config fields reference

Field
Type
Property name
string
client_id
string
client_secret
integer
org_id
string
start_date
integer
backoff_factor
string
end_date
integer
lookback_window
integer
num_workers
string
timezone
string
token_refresh_endpoint

Changelog​

Expand to review
VersionDatePull RequestSubject
1.1.222026-10-2689712Report expired client secrets and rejected report dates as configuration errors, explain missing API roles, show Apple's message on other API errors, add biddingStrategy, targetCpa and automatedKeywordsRequired, make Time Zone and Token Refresh Endpoint optional, hide Exponential Backoff Factor and Token Refresh Endpoint in the UI, and update the base image
1.1.212026-10-2089117Update dependencies
1.1.202026-10-1388507Update dependencies
1.1.192026-10-0687754Update dependencies
1.1.182026-09-2987075Update dependencies
1.1.172026-09-2286540Update dependencies
1.1.162026-09-1585951Update dependencies
1.1.152026-09-0884472Update dependencies
1.1.142026-08-1183830Update dependencies
1.1.132026-08-0483353Update dependencies
1.1.122026-07-2882825Update dependencies
1.1.112026-07-2182340Update dependencies
1.1.102026-07-1481722Update dependencies
1.1.92026-06-3080968Update dependencies
1.1.82026-06-2380356Update dependencies
1.1.72026-06-1679764Update dependencies
1.1.62026-06-0979235Update dependencies
1.1.52026-06-0278565Update dependencies
1.1.42026-05-1278029Refresh expired OAuth access tokens before retrying failed Apple Ads API requests
1.1.32026-05-0576973Fix ads_report_daily broken incremental sync, remove incorrect keyword error predicate, and enable concurrent partition processing to reduce heartbeat timeouts
1.1.22026-04-2877141Update dependencies
1.1.12026-04-2176507Update dependencies
1.1.02026-04-1469218Add two new streams - ads & ads_report_daily
1.0.112026-03-3175879Update dependencies
1.0.102026-03-2475015Update dependencies
1.0.92026-03-1074512Update dependencies
1.0.82026-03-0374180Update dependencies
1.0.72026-02-0672690Update dependencies
1.0.62026-01-2071888Update dependencies
1.0.52026-01-1471435Update dependencies
1.0.42025-12-1870810Update dependencies
1.0.32025-11-2569891Update dependencies
1.0.22025-11-1869577Update dependencies
1.0.12025-10-2968392Update dependencies
1.0.02025-10-2166557Update adgroups_report_daily and keywords_report_daily to use global state cursor
0.8.102025-10-1467979Update dependencies
0.8.92025-10-0767173Update dependencies
0.8.82025-09-3066272Update dependencies
0.8.72025-09-1566197Update to CDK v7
0.8.62025-08-2365312Update dependencies
0.8.52025-08-0964663Update dependencies
0.8.42025-07-1963453Update dependencies
0.8.32025-07-1263087Update dependencies
0.8.22025-06-1661626Update dependencies
0.8.12025-05-2960627Update dependencies
0.8.02025-05-1360241Add token refresh endpoint override configuration override
0.7.92025-05-1059888Update dependencies
0.7.82025-05-0359308Update dependencies
0.7.72025-04-2658712Update dependencies
0.7.62025-04-1958275Update dependencies
0.7.52025-04-1257658Update dependencies
0.7.42025-04-0557158Update dependencies
0.7.32025-03-2956573Update dependencies
0.7.22025-03-2556383add countryorregion to report schemas
0.7.12025-03-2256109Update dependencies
0.7.02025-03-2055839countryOrRegion metadata info included
0.6.02025-03-2055785Add timezone config parameter
0.5.12025-03-0855366Update dependencies
0.5.02025-03-0755210Remove primary keys
0.4.32025-03-0154873Update dependencies
0.4.22025-02-2554646Fix paginator settings for incremental report streams
0.4.12025-02-2254284Update dependencies
0.4.02025-02-2154170Externalize backoff factor and lookback window configurations
0.3.32025-02-1853920Update dependencies
0.3.22025-02-1453685Fix granularity to daily
0.3.12025-02-0853422Update dependencies
0.3.02025-02-0553136Update API version to V5
0.2.92025-02-0152899Update dependencies
0.2.82025-01-2552197Update dependencies
0.2.72025-01-1851745Update dependencies
0.2.62025-01-1151249Update dependencies
0.2.52024-12-2850469Update dependencies
0.2.42024-12-2150155Update dependencies
0.2.32024-12-1449561Update dependencies
0.2.22024-12-1247751Update dependencies
0.2.12024-11-1248440Set authentication grant_type to client_credentials
0.2.02024-10-0546288Migrate to Manifest-only
0.1.202024-09-2946153Update dependencies
0.1.192024-09-2245803Update dependencies
0.1.182024-09-1545474Update dependencies
0.1.172024-09-0845326Update dependencies
0.1.162024-09-0145013Update dependencies
0.1.152024-08-2544654Update dependencies
0.1.142024-08-1844322Update dependencies
0.1.132024-08-1343912Update dependencies
0.1.122024-08-1143514Update dependencies
0.1.112024-08-0443195Update dependencies
0.1.102024-07-2842660Update dependencies
0.1.92024-07-2142225Update dependencies
0.1.82024-07-1441722Update dependencies
0.1.72024-07-1141546Update dependencies
0.1.62024-07-1040832Update dependencies
0.1.52024-06-2640364Update dependencies
0.1.42024-06-2340186Update dependencies
0.1.32024-06-0538967[autopull] Upgrade base image to v1.2.1
0.1.22024-05-3038502[autopull] base image + poetry + up_to_date
0.1.12023-07-1128153Fix manifest duplicate key (no change in behavior for the syncs)
0.1.02023-04-1819557Initial release with campaigns, adgroups & keywords streams (base and daily reports)
Was this page helpful?