Skip to main content

Apple Ads (Apple Search Ads)

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable Self-Managed EnterpriseAvailable PyAirbyte
Support Level
Marketplace
Connector Version
1.1.3 (last updated 2 days ago)
Definition ID
e59c8416-c2fa-4bd3-9e95-52677ea281c1

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

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 OAuth client id and client secret generated for an API user (see Step 1 below).

Setup guide​

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

The connector authenticates to the Apple Ads Campaign Management API using OAuth 2 client credentials. An account administrator creates an API user, generates a key pair, and produces a client id and client secret. Apple's full guide is at Implementing OAuth for the Apple Ads API. The high-level steps are:

  1. From Apple Ads, sign in as an account administrator and go to Account Settings → User Management.
  2. Click Invite Users and assign the user an API user role.
  3. Generate a private and public key pair, upload the public key for the API user, and create a client secret.
  4. Note the resulting Client ID and Client Secret. You'll enter them into Airbyte in Step 2.

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. Enter the Client ID and Client Secret from Step 1.
  5. For Start Date and End Date, enter dates in YYYY-MM-DD format. If End Date is blank, Airbyte syncs up to today. Apple's reporting API limits how far back daily data is available; requests for dates outside the supported window return no data.
  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. For Exponential Backoff Factor, enter a value between 1 and 20. This controls how aggressively the connector backs off when Apple's API returns rate-limit (429) or server (500) errors. The default is 5; increase it for very large accounts that frequently hit rate limits.
  9. (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.
  10. (Optional) For Token Refresh Endpoint, override the default Apple OAuth token endpoint. Use this only if you proxy outbound requests; most users should leave it at the default.
  11. Click Set up source.

Supported sync modes​

The Apple Ads source connector supports the following sync modes:

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 default to (date, campaignId) as the primary key. Because each row is also broken out by countryOrRegion, the connector exposes a separate countryorregion field. If your account targets multiple countries or regions, add countryorregion to the primary key in the connection's stream settings to deduplicate correctly.

Performance considerations​

  • Apple's API enforces rate limits and recommends exponential retry. The connector automatically retries 429 and 500 responses; tune the Exponential Backoff Factor to control how aggressively it backs off.
  • 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.

Reference​

Config fields reference

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

Changelog​

Expand to review
VersionDatePull RequestSubject
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-0169218Add 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-0372690Update 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-12TBDUpdate 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-1561626Update dependencies
0.8.12025-05-1760627Update 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-0555210Remove primary keys
0.4.32025-03-0154873Update dependencies
0.4.22025-02-2454646Fix paginator settings for incremental report streams
0.4.12025-02-2254284Update dependencies
0.4.02025-02-2054170Externalize backoff factor and lookback window configurations
0.3.32025-02-1553920Update dependencies
0.3.22025-02-1453685Fix granularity to daily
0.3.12025-02-0853422Update dependencies
0.3.02025-02-0353136Update 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-0848440Set authentication grant_type to client_credentials
0.2.02024-10-0146288Migrate to Manifest-only
0.1.202024-09-2846153Update dependencies
0.1.192024-09-2145803Update dependencies
0.1.182024-09-1445474Update dependencies
0.1.172024-09-0745326Update dependencies
0.1.162024-08-3145013Update dependencies
0.1.152024-08-2444654Update dependencies
0.1.142024-08-1744322Update dependencies
0.1.132024-08-1243912Update dependencies
0.1.122024-08-1043514Update dependencies
0.1.112024-08-0343195Update dependencies
0.1.102024-07-2742660Update dependencies
0.1.92024-07-2042225Update dependencies
0.1.82024-07-1341722Update dependencies
0.1.72024-07-1041546Update dependencies
0.1.62024-07-0940832Update dependencies
0.1.52024-06-2540364Update dependencies
0.1.42024-06-2240186Update dependencies
0.1.32024-06-0438967[autopull] Upgrade base image to v1.2.1
0.1.22024-05-2138502[autopull] base image + poetry + up_to_date
0.1.12023-07-1128153Fix manifest duplicate key (no change in behavior for the syncs)
0.1.02022-11-1719557Initial release with campaigns, adgroups & keywords streams (base and daily reports)
Was this page helpful?