Advanced Analytica Advanced Analytica: IBOM
← All connectors
Bing Ads logo

Source connector

Bing Ads

Set up Bing Ads as a source and move its data into your chosen destination.

Version 3.0.23 certified generally available

Bing Ads

Use this page to set up the Bing Ads source connector and find reference information.

Prerequisites

  • Microsoft Advertising account
  • Microsoft Developer Token

Setup guide

For Airbyte Open Source, set up your application to get a Client ID, Client Secret, and Refresh Token:

  1. Register your application in the Azure portal.
  2. Request user consent to get the authorization code.
  3. Use the authorization code to get a refresh token.

:::note

Microsoft refresh tokens remain valid for 90 days and rotate each time they’re used. Airbyte saves the rotated refresh token whenever it refreshes the access token. Your connection therefore stays authenticated if it syncs at least once every 90 days. If it doesn’t sync for over 90 days, the refresh token expires. You must then repeat the authorization process to get a new token. The full authentication process is described here. Authenticate using the personal or work email address you use for the Microsoft Advertising platform.

:::

Step 1: Set up Bing Ads

  1. Get your Microsoft developer token. You need a developer token and valid user credentials to use Bing Ads APIs. See Microsoft Advertising docs for more information.

    1. Sign in with Super Admin credentials at the Microsoft Advertising Developer Portal account tab.
    2. Choose the user you want to associate with the developer token. An application typically needs only one universal token, regardless of how many users it supports.
    3. Click the Request Token button.
  2. If your OAuth app has a custom tenant, you may be unable to use Microsoft’s recommended common tenant. Enter the custom tenant in the Tenant ID field when you set up the connector.

:::info

The authentication URL uses the tenant. For example: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize

:::

Step 2: Set up the source connector in Airbyte

Airbyte Cloud

  1. Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Bing Ads from the Source type dropdown.
  4. Enter a name for the Bing Ads connector.
  5. For Tenant ID, enter the custom tenant or use the common tenant.
  6. Add the developer token from Step 1.
  7. For Account Names Predicates, see predicates in the Bing Ads docs. This filters your accounts using a specified operator and account name. You can use multiple predicate pairs. The Operator is either Contains or Equals. The Account Name is the value compared with the Account Name field using the specified operator. For operator=Contains and name=Dev, all accounts with names containing “Dev” will be replicated. For operator=Equals and name=Airbyte, all accounts with names equal to “Airbyte” will be replicated. Account Name values aren’t case-sensitive.
  8. For Reports Replication Start Date, enter the date in YYYY-MM-DD format. Data added on or after this date will be replicated. If this field is blank, Airbyte will replicate all data from previous and current calendar years.
  9. For Lookback window, enter how many days before the saved report cursor Airbyte should re-read. This captures late conversions or corrected metrics. Round conversion windows measured in hours or minutes up to whole days. This setting applies to all report streams in incremental mode, including budget summary and custom reports. It applies whether or not Reports Replication Start Date is set. That start date remains the earliest date to read. Bulk entity streams ignore this setting. If you aren’t using incremental report streams, keep the default value of 0.
  10. For Custom Reports, see the custom reports section.
  11. For Report Name, enter the name you want for your custom report.
  12. For Reporting Data Object, add the Bing Ads Reporting Object you want to sync in the custom report.
  13. For Columns, add the Reporting Data Object columns you want to see in the custom report.
  14. For Aggregation, add the time aggregation. See the report aggregation section.
  15. (Optional) For Disable Custom Report Names Camel to Snake Case Conversion, enable this option to use the exact report name. This prevents automatic conversion from camelCase to snake_case. See custom report name conversion for details.
  16. Click Authenticate your Bing Ads account.
  17. Log in and authorize the Bing Ads account.
  18. Click Set up source.

Airbyte Open Source

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Bing Ads from the Source type dropdown.
  4. Enter a name for the Bing Ads connector.
  5. For Tenant ID, enter the custom tenant or use the common tenant.
  6. Enter the Client ID, Client Secret, Refresh Token, and Developer Token from Step 1.
  7. For Account Names Predicates, see predicates in the Bing Ads docs. This filters your accounts using a specified operator and account name. You can use multiple predicate pairs. The Operator is either Contains or Equals. The Account Name is the value compared with the Account Name field using the specified operator. For operator=Contains and name=Dev, all accounts with names containing “Dev” will be replicated. For operator=Equals and name=Airbyte, all accounts with names equal to “Airbyte” will be replicated. Account Name values aren’t case-sensitive.
  8. For Reports Replication Start Date, enter the date in YYYY-MM-DD format. Data added on or after this date will be replicated. If this field is blank, Airbyte will replicate all data from previous and current calendar years.
  9. For Lookback window, enter how many days before the saved report cursor Airbyte should re-read. This captures late conversions or corrected metrics. Round conversion windows measured in hours or minutes up to whole days. This setting applies to all report streams in incremental mode, including budget summary and custom reports. It applies whether or not Reports Replication Start Date is set. That start date remains the earliest date to read. Bulk entity streams ignore this setting. If you aren’t using incremental report streams, keep the default value of 0.
  10. For Custom Reports, see the custom reports section.
  11. For Report Name, enter the name you want for your custom report.
  12. For Reporting Data Object, add the Bing Ads Reporting Object you want to sync in the custom report.
  13. For Columns, add the Reporting Data Object columns you want to see in the custom report.
  14. For Aggregation, select the time aggregation. See the report aggregation section.
  15. (Optional) For Disable Custom Report Names Camel to Snake Case Conversion, enable this option to use the exact report name. This prevents automatic conversion from camelCase to snake_case. See custom report name conversion for details.
  16. Click Set up source.

Supported sync modes

The Bing Ads source connector supports these sync modes:

Supported streams

The Bing Ads source connector supports these streams. See the Bing Ads API for more information.

Basic streams

Report streams

:::warning

Removing fields in the replication settings doesn’t change the report’s API request. Reports always include every field in the stream schema. Invisible grouping by removed fields may therefore make report results inaccurate. Use a custom report if you need a report with fewer fields.

:::

:::info

You can define a primary key for the following report streams. Set it on your connection’s Replication tab:

  • Ad Group Impression Performance Report, example: [AdGroupId, Status, TimePeriod, AccountId]
  • Geographic Performance Report, example: [AdGroupId, Country, State, MetroArea, City]
  • Account Impression Performance Report, example: [AccountName, AccountNumber, AccountId, TimePeriod]

These examples are only a guide. Choose a primary key that fits your data. See user-defined primary key for details.

:::

Entity-relationship diagram

Custom reports

Build your own report by providing:

  • Report Name: the stream name
  • Reporting Data Object: the Bing Ads reporting data object, which you can find here. You can use any data object ending in ReportRequest for custom reports.
  • Columns: the reporting object columns you want to sync. Find available columns on the ReportRequest data object page. Follow the ...ReportColumn link in the Bing Ads docs. The report must include every required column. Each report generally needs at least one attribute column. It also needs at least one performance statistics column that isn’t for impression share. You can’t add columns absent from the Bing Ads docs, and you can’t omit every optional column.
  • Aggregation: Hourly, Daily, Weekly, Monthly, DayOfWeek, HourOfDay, WeeklyStartingMonday, Summary. See report aggregation.

Custom report name conversion

By default, custom report names are automatically converted from camelCase to snake_case. For example:

  • MyCustomReport becomes my_custom_report
  • CampaignPerformanceDaily becomes campaign_performance_daily
  • keywordAnalysisReport becomes keyword_analysis_report

This conversion keeps names consistent with Airbyte’s naming conventions and compatible with most data destinations.

Disable name conversion

You can keep exact custom report names by disabling automatic conversion for each per-report basis. Set the Disable Custom Report Names Camel to Snake Case Conversion option to true for each custom report.

When you disable conversion for a report:

  • Airbyte uses that report’s name exactly as specified
  • Airbyte doesn’t convert that report’s name from camelCase to snake_case
  • You control the resulting stream name for that report
  • Other custom reports still use the default conversion unless you disable it

:::warning Breaking change warning

Changing this setting for an existing custom report will create a new stream and remove the old one. This breaking change may affect your data pipelines and downstream processes.

For example, you may have an existing custom report named MyCustomReport, which creates a stream called my_custom_report. If you later disable conversion, Airbyte creates a new stream called MyCustomReport. The old my_custom_report stream will no longer be available.

Be careful when modifying this setting for existing custom reports in production environments.

:::

Example configuration:

{
  "custom_reports": [
    {
      "name": "MyExactReportName",
      "reporting_object": "CampaignPerformanceReportRequest",
      "report_columns": ["CampaignName", "Impressions", "Clicks"],
      "report_aggregation": "Daily",
      "disable_custom_report_names_camel_to_snake_conversion": true
    },
    {
      "name": "AnotherReport",
      "reporting_object": "AccountPerformanceReportRequest",
      "report_columns": ["AccountName", "Impressions", "Clicks"],
      "report_aggregation": "Daily"
    }
  ]
}

In this example:

  • The first report is named exactly MyExactReportName because conversion is disabled
  • The second report is named another_report because the default conversion applies

Report aggregation

You can aggregated every report synced by this connector using hourly, daily, weekly, or monthly time windows.

For example, select daily aggregation to create one row for each day in the report period. Each row shows the impressions recorded that day.

The report name shows its aggregation window. For example, account_performance_report_hourly is the Account Performance Report with hourly aggregation.

Upgrade the connector

See the Bing Ads Migration Guide for breaking changes and migration steps.

Limitations and troubleshooting

Expand to see details about Bing Ads connector limitations and troubleshooting.

Connector limitations

Rate limits

The Bing Ads API limits requests from all Microsoft Advertising clients. See here for detailed information. Microsoft doesn’t publish specific rate limits for the Bing Ads API. If you exceed the service call limit, the API returns error code 117 (CallRateExceeded). The connector retries automatically. However, persistent throttling may slow syncs for large accounts.

Bulk stream incremental behaviour

Bulk streams use the Microsoft Bulk API. These streams are Ad Group Labels, App Install Ads, App Install Ad Labels, Campaign Labels, Keywords, Keyword Labels, Labels, and Budget. In incremental mode, the Bulk API ignores LastSyncTimeInUTC for dates over 30 days ago. This triggers a full download. After a gap exceeding 30 days, the first sync therefore downloads all data, regardless of state.

Troubleshooting

  • Find common troubleshooting guidance for the Bing Ads source connector on the Airbyte Forum.

IP allow list

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

Changelog

Expand to review
VersionDatePull RequestSubject
3.0.232026-11-1091310Declare the refreshed access_token and token_expiry_date as hidden spec fields so the access token is masked
3.0.222026-11-1091361Update dependencies
3.0.212026-11-0388968Add actionable messages for Microsoft Entra refresh token errors
3.0.202026-11-0389720Sync App, Hotel and Objective-based campaigns (and their ad groups and ads), which were previously skipped
3.0.192026-11-0390478Update dependencies
3.0.182026-11-0289620Apply lookback only to report streams to avoid unnecessary full downloads of bulk entities
3.0.172026-10-2789793Update dependencies
3.0.162026-10-2189609Classify expired file download URL errors as transient with a clearer error message
3.0.152026-10-2089107Update dependencies
3.0.142026-10-1388521Update dependencies
3.0.132026-10-0687771Update dependencies
3.0.122026-09-2987061Update dependencies
3.0.112026-09-2286541Update dependencies
3.0.102026-09-1585943Update dependencies
3.0.92026-09-0885411Update dependencies
3.0.82026-08-1884507Update dependencies
3.0.72026-08-1183859Update dependencies
3.0.62026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
3.0.52026-07-281082Roll Cloud back to 3.0.3 — 3.0.4 is built on SDM 7.23.7, which breaks bundled custom components
3.0.42026-07-2882806Update dependencies
3.0.32026-07-2182339Update dependencies
3.0.22026-07-1477143Update dependencies
3.0.12026-07-0879625Add refresh_token_updater to persist rotated Microsoft OAuth refresh tokens; remove non-standard OAuth refresh params
3.0.02026-05-1278031Breaking: include every attribute (dimension) column in the primary keys of all report streams to prevent silent row collapse at the destination during incremental append+dedup. A stream reset is required for the affected report streams after upgrading.
2.23.172026-05-2978518Add num_workers config for user-adjustable concurrency
2.23.17-rc.22026-05-2778438Revert concurrency to 10, add num_workers config and HTTP API budget
2.23.17-rc.12026-05-2678438Enable progressive rollout for concurrency tuning
2.23.162026-04-2176515Update dependencies
2.23.152026-04-0876165Promote 2.23.15-rc.3 to GA — fixes SAS token expiry during report downloads
2.23.15-rc.32026-04-0276053Fix SAS token expiry during report downloads by re-polling for fresh URL before each download
2.23.15-rc.22026-03-3074885Fix OOM on large report downloads by using streaming ZIP decoder and reducing concurrency
2.23.15-rc.12026-03-1274745Increase default concurrency from 2 to 40 to test rate limit behavior
2.23.142026-03-1074483Update dependencies
2.23.132026-03-0373654Use streaming decompression in BingAdsGzipCsvDecoder to prevent OOM on large accounts
2.23.122026-03-0373829Update dependencies
2.23.112026-02-1769578Update dependencies
2.23.102026-02-0572264Update CDK version from 7.4.1 to 7.6.5
2.23.92025-10-2968883Update dependencies
2.23.82025-10-2168406Update dependencies
2.23.72025-10-1468008Update dependencies
2.23.62025-10-0767170Update dependencies
2.23.52025-09-3066038Update dependencies
2.23.42025-09-1666234Promoting release candidate 2.23.4-rc.1 to a main version.
2.23.4-rc.12025-09-1065894Fix Custom Report Names - Add Option to Disable camel_case_to_snake_case
2.23.32025-09-1065995Update to CDK v7
2.23.22025-08-1664952Always decompress bulk download response
2.23.12025-07-2660669Update dependencies
2.23.02025-07-0962872Promoting release candidate 2.23.0-rc.1 to a main version.
2.23.0-rc.12025-07-0762520Migrate Source Bing Ads to manifest-only
2.22.02025-07-0262087Migrate custom report streams to manifest
2.21.02025-06-2662079Migrate search_query_performance_report and product_search_query_performance_report streams to manifest
2.20.02025-06-2662060Migrate budget_summary_report stream to manifest, refactor ad_performance_report and account_performance_report to use dynamic definition
2.19.02025-06-2562073Migrate audience_peformance_report, goals_and_funnels_report, account_impression_performance_report and user_location_performance_report streams to manifest
2.18.02025-06-2562013Migrate product_dimension_performance_report, ad_group_impression_performance_report and campaign_impression_performance_report streams to manifest
2.17.02025-06-2561719Migrate keywords, keyword_labels, campaign_labels and budget streams to manifest
2.16.02025-06-2461725Migrate keyword_performance_report and geographic_performance_report streams to manifest
2.15.02025-06-2361675Migrate ad_group_performance_report streams to manifest
2.14.02025-06-1861693Migrate ad_group_labels, app_install_ad_labels, and app_install_ads streams to manifest
2.13.02025-06-1661495Migrate campaign_performance_report and age_gender_audience_report streams to manifest
2.12.02025-06-1261578Promoting release candidate 2.12.0-rc.1 to a main version.
2.12.0-rc.12025-06-1260947Migrate ads and ad_groups streams to manifest
2.11.02025-06-1061517Promoting release candidate 2.11.0-rc.1 to a main version.
2.11.0-rc.12025-06-0961325Migrate account_performance_report streams and labels stream to manifest
2.10.02025-06-0261329Promoting release candidate 2.10.0-rc.1 to a main version.
2.10.0-rc.12025-06-0159750Migrate ad_performance_reports and campaigns streams to manifest
2.9.42025-05-2960909Remove account records if duplicated caused by predicate
2.9.32025-05-2860929Fix duplicated slices/jobs when reports_start_date is not set
2.9.22025-05-2260832Fix handling of account_names predicate in declarative stream
2.9.12025-05-1054233Update dependencies
2.9.02025-05-0759719Promoting release candidate 2.9.0-rc.1 to a main version.
2.9.0-rc.12025-05-0659136Bump CDK v6 and migrate Accounts stream to low-code
2.8.132025-02-1553882Update dependencies
2.8.122025-02-0152930Update dependencies
2.8.112025-01-2552198Update dependencies
2.8.102025-01-1851735Update dependencies
2.8.92025-01-1151230Update dependencies
2.8.82025-01-0450905Update dependencies
2.8.72024-12-2850443Update dependencies
2.8.62024-12-2150181Update dependencies
2.8.52024-12-1449283Update dependencies
2.8.42024-11-2548650Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
2.8.32024-11-0448169Update dependencies
2.8.22024-10-2947850Update dependencies
2.8.12024-10-2847093Update dependencies
2.8.02024-10-2146991Update CDK to v5
2.7.92024-10-1246847Update dependencies
2.7.82024-10-0546504Update dependencies
2.7.72024-09-2846151Update dependencies
2.7.62024-09-2145512Update dependencies
2.7.52024-09-0745246Update dependencies
2.7.42024-08-3144276Update dependencies
2.7.32024-08-1243742Update dependencies
2.7.22024-08-1043591Update dependencies
2.7.12024-08-0343245Update dependencies
2.7.02024-07-3142548Migrate to CDK v4.1.0
2.6.122024-07-2742812Update dependencies
2.6.112024-07-2042360Update dependencies
2.6.102024-07-1341875Update dependencies
2.6.92024-07-1041383Update dependencies
2.6.82024-07-0941314Update dependencies
2.6.72024-07-0640906Update dependencies
2.6.62024-07-0534966Add support for Performance Max campaigns.
2.6.52024-06-2740585Replaced deprecated AirbyteLogger with logging.Logger
2.6.42024-06-2540457Update dependencies
2.6.32024-06-2240006Update dependencies
2.6.22024-06-0639177[autopull] Upgrade base image to v1.2.2
2.6.12024-05-0236632Schema descriptions
2.6.02024-04-2535878Add missing fields in keyword_performance_report
2.5.02024-03-2135891Accounts stream: add TaxCertificate field to schema
2.4.02024-03-1936267Pin airbyte-cdk version to ^0
2.3.02024-03-0535812New streams: Audience Performance Report, Goals And Funnels Report, Product Dimension Performance Report.
2.2.02024-02-1335201New streams: Budget and Product Dimension Performance.
2.1.42024-02-1235179Manage dependencies with Poetry
2.1.32024-01-3134712Fix duplicated records for report-based streams
2.1.22024-01-0934045Speed up record transformation
2.1.12023-12-1533500Fix state setter when state was provided
2.1.02023-12-0533095Add account filtering
2.0.12023-11-1632597Fix start date parsing from stream state
2.0.02023-11-0731995Schema update for Accounts, Campaigns and Search Query Performance Report streams. Convert date and date-time fields to standard RFC3339
1.13.02023-11-1332306Add Custom reports and decrease backoff max tries number
1.12.12023-11-1032422Normalize numeric values in reports
1.12.02023-11-0932340Remove default start date in favor of Time Period - Last Year and This Year, if start date is not provided
1.11.02023-11-0632201Skip broken CSV report files
1.10.02023-11-0632148Add new fields to stream Ads: “BusinessName”, “CallToAction”, “Headline”, “Images”, “Videos”, “Text”
1.9.02023-11-0332131Add “CampaignId”, “AccountId”, “CustomerId” fields to Ad Groups, Ads and Campaigns streams.
1.8.02023-11-0232059Add new streams CampaignImpressionPerformanceReport (daily, hourly, weekly, monthly)
1.7.12023-11-0232088Raise config error when user does not have accounts
1.7.02023-11-0132027Add new streams AdGroupImpressionPerformanceReport
1.6.02023-10-3132008Add new streams Keywords
1.5.02023-10-3031952Add new streams Labels, App install ads, Keyword Labels, Campaign Labels, App Install Ad Labels, Ad Group Labels
1.4.02023-10-2731885Add new stream: AccountImpressionPerformanceReport (daily, hourly, weekly, monthly)
1.3.02023-10-2631837Add new stream: UserLocationPerformanceReport (daily, hourly, weekly, monthly)
1.2.02023-10-2431783Add new stream: SearchQueryPerformanceReport (daily, hourly, weekly, monthly)
1.1.02023-10-2431712Add new stream: AgeGenderAudienceReport (daily, hourly, weekly, monthly)
1.0.22023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
1.0.12023-10-1631432Remove primary keys from the geographic performance reports - complete what was missed in version 1.0.0
1.0.02023-10-1131277Remove primary keys from the geographic performance reports
0.2.32023-09-2830834Wrap auth error with the config error
0.2.22023-09-2730791Fix missing fields for geographic performance reports
0.2.12023-09-0430128Add increasing download timeout if ReportingDownloadException occurs
0.2.02023-08-1727619Add Geographic Performance Report
0.1.242023-06-2227619Retry request after facing temporary name resolution error
0.1.232023-05-1125996Implement a retry logic if SSL certificate validation fails
0.1.222023-05-0824223Add CampaignLabels report column in campaign performance report
0.1.212023-04-2825668Add undeclared fields to accounts, campaigns, campaign_performance_report, keyword_performance_report and account_performance_report streams
0.1.202023-03-0923663Add lookback window for performance reports in incremental mode
0.1.192023-03-0823868Add dimensional-type columns for reports
0.1.182023-01-3022073Fix null values in the Keyword column of keyword_performance_report streams
0.1.172022-12-1020005Add Keyword to keyword_performance_report stream
0.1.162022-10-1217873Fix: added missing campaign types in (Audience, Shopping and DynamicSearchAds) in campaigns stream
0.1.152022-10-0317505Fix: limit cache size for ServiceClient instances
0.1.142022-09-2917403Fix: limit cache size for ReportingServiceManager instances
0.1.132022-09-2917386Migrate to per-stream states
0.1.122022-09-0516335Added backoff for socket.timeout
0.1.112022-08-2515684 (published in 15987)Fixed log messages being unreadable
0.1.102022-08-1215602Fixed bug caused Hourly Reports to crash due to invalid fields set
0.1.92022-08-0214862Added missing columns
0.1.82022-06-1513801All reports hourly/daily/weekly/monthly will be generated by default, these options are removed from input configuration
0.1.72022-05-1712937Added OAuth2.0 authentication method, removed redirect_uri from input configuration
0.1.62022-04-3012500Improve input configuration copy
0.1.52022-01-0111652Rebump attempt after DockerHub failure at registring the 0.1.4
0.1.42022-03-2211311Added optional Redirect URI & Tenant ID to spec
0.1.32022-01-149510Fixed broken dependency that blocked connector’s operations
0.1.22021-12-148429Update titles and descriptions
0.1.12021-08-315750Added reporting streams
0.1.02021-07-224911Initial release supported core streams (Accounts, Campaigns, Ads, AdGroups)
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.