airbyte/docs/integrations/sources/apple-search-ads.md

Apple Ads (Apple Search Ads)

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

Setup guide

Step 1: Set up Apple Ads

1. With an administrator account, create an API user role from the Apple Ads UI.
2. Then implement OAuth for your API user in order to the required Client Secret and Client Id.

Step 2: Set up the source connector in Airbyte

For Airbyte Open Source

1. Log in to your Airbyte Open Source account.
2. Click Sources and then click + New source.
3. On the Set up the source page, select Apple Ads from the Source type dropdown.
4. Enter a name for your source.
5. For Org Id, enter the Id of your organization (found in the Apple Ads UI).
6. Enter the Client ID and the Client Secret from Step 1.
7. For Start Date and End Date, enter the date in YYYY-MM-DD format. For DAILY reports, the Start Date can't be earlier than 90 days from today. If the End Date field is left blank, Airbyte will replicate data to today.
8. For Time Zone, select either UTC (Coordinated Universal Time) or ORTZ (Organization Time Zone). The default is UTC.
9. For Lookback Window, enter the number of days (1-30) to re-fetch data during incremental syncs. The default is 30 days, which matches Apple Search Ads' attribution window. You can decrease this value to sync smaller amounts of data on each incremental sync, but this may result in missing late data attributions.
10. For Exponential Backoff Factor, enter a value between 1 and 20 to control the delay between retry attempts when rate limits are encountered. The default is 5. Increase this value when syncing large amounts of data to reduce the chance of synchronization failures.
11. Click Set up source.

Supported sync modes

The Apple Ads source connector supports the following sync modes:

• Full Refresh - Overwrite
• Full Refresh - Append
• Incremental - Append
• Incremental - Append + Deduped

Supported Streams

The Apple Ads source connector supports the following streams. For more information, see the Apple Ads API.

Base streams

• campaigns
• adgroups
• keywords

Report Streams

::: note The usual primary keys for reports are date and campaignId. However, there are cases where active fields must be selected as primary keys to ensure data deduplication is correct. One example is countryOrRegion. :::

• campaigns_report_daily
• adgroups_report_daily
• keywords_report_daily

Report aggregation

The Apple Ads currently offers aggregation at hourly, daily, weekly, or monthly level.

However, at this moment and as indicated in the stream names, the connector only offers data with daily aggregation.

Changelog

Expand to review

Version	Date	Pull Request	Subject
1.0.3	2025-11-25	69891	Update dependencies
1.0.2	2025-11-18	69577	Update dependencies
1.0.1	2025-10-29	68392	Update dependencies
1.0.0	2025-10-15	66557	Update adgroups_report_daily and keywords_report_daily to use global state cursor
0.8.10	2025-10-14	67979	Update dependencies
0.8.9	2025-10-07	67173	Update dependencies
0.8.8	2025-09-30	66272	Update dependencies
0.8.7	2025-09-12	TBD	Update to CDK v7
0.8.6	2025-08-23	65312	Update dependencies
0.8.5	2025-08-09	64663	Update dependencies
0.8.4	2025-07-19	63453	Update dependencies
0.8.3	2025-07-12	63087	Update dependencies
0.8.2	2025-06-15	61626	Update dependencies
0.8.1	2025-05-17	60627	Update dependencies
0.8.0	2025-05-13	60241	Add token refresh endpoint override configuration override
0.7.9	2025-05-10	59888	Update dependencies
0.7.8	2025-05-03	59308	Update dependencies
0.7.7	2025-04-26	58712	Update dependencies
0.7.6	2025-04-19	58275	Update dependencies
0.7.5	2025-04-12	57658	Update dependencies
0.7.4	2025-04-05	57158	Update dependencies
0.7.3	2025-03-29	56573	Update dependencies
0.7.2	2025-03-25	56383	add countryorregion to report schemas
0.7.1	2025-03-22	56109	Update dependencies
0.7.0	2025-03-20	55839	countryOrRegion metadata info included
0.6.0	2025-03-20	55785	Add timezone config parameter
0.5.1	2025-03-08	55366	Update dependencies
0.5.0	2025-03-05	55210	Remove primary keys
0.4.3	2025-03-01	54873	Update dependencies
0.4.2	2025-02-24	54646	Fix paginator settings for incremental report streams
0.4.1	2025-02-22	54284	Update dependencies
0.4.0	2025-02-20	54170	Externalize backoff factor and lookback window configurations
0.3.3	2025-02-15	53920	Update dependencies
0.3.2	2025-02-14	53685	Fix granularity to daily
0.3.1	2025-02-08	53422	Update dependencies
0.3.0	2025-02-03	53136	Update API version to V5
0.2.9	2025-02-01	52899	Update dependencies
0.2.8	2025-01-25	52197	Update dependencies
0.2.7	2025-01-18	51745	Update dependencies
0.2.6	2025-01-11	51249	Update dependencies
0.2.5	2024-12-28	50469	Update dependencies
0.2.4	2024-12-21	50155	Update dependencies
0.2.3	2024-12-14	49561	Update dependencies
0.2.2	2024-12-12	47751	Update dependencies
0.2.1	2024-11-08	48440	Set authentication grant_type to client_credentials
0.2.0	2024-10-01	46288	Migrate to Manifest-only
0.1.20	2024-09-28	46153	Update dependencies
0.1.19	2024-09-21	45803	Update dependencies
0.1.18	2024-09-14	45474	Update dependencies
0.1.17	2024-09-07	45326	Update dependencies
0.1.16	2024-08-31	45013	Update dependencies
0.1.15	2024-08-24	44654	Update dependencies
0.1.14	2024-08-17	44322	Update dependencies
0.1.13	2024-08-12	43912	Update dependencies
0.1.12	2024-08-10	43514	Update dependencies
0.1.11	2024-08-03	43195	Update dependencies
0.1.10	2024-07-27	42660	Update dependencies
0.1.9	2024-07-20	42225	Update dependencies
0.1.8	2024-07-13	41722	Update dependencies
0.1.7	2024-07-10	41546	Update dependencies
0.1.6	2024-07-09	40832	Update dependencies
0.1.5	2024-06-25	40364	Update dependencies
0.1.4	2024-06-22	40186	Update dependencies
0.1.3	2024-06-04	38967	[autopull] Upgrade base image to v1.2.1
0.1.2	2024-05-21	38502	[autopull] base image + poetry + up_to_date
0.1.1	2023-07-11	28153	Fix manifest duplicate key (no change in behavior for the syncs)
0.1.0	2022-11-17	19557	Initial release with campaigns, adgroups & keywords streams (base and daily reports)