Microsoft Advertising

Microsoft Advertising, popularly called Microsoft Ads or Bing Ads, is a pay-per-click (PPC) advertising platform for the Bing and Yahoo search engines. It displays your Ads based on the keywords in a user’s search query on and The reports it generates provide detailed statistics about your Microsoft Advertising accounts, campaigns, and Adgroups. The information can help you track finances, measure Ad performance, and adjust settings to optimize your budget or campaigns.

For creating Pipelines using this Source, Hevo provides you a fully managed BigQuery data warehouse as a possible Destination. This option remains available till the time you set up your first BigQuery Destination irrespective of any other Destinations that you may have. With the managed warehouse, you are only charged the cost that Hevo incurs for your project in Google BigQuery. The invoice is generated at the end of each month and payment is recovered as per the payment instrument you have set up. You can now create your Pipeline and directly start analyzing your Source data. Read Hevo Managed Google BigQuery.


Microsoft Ads offers two types of accounts:

  • Advertiser (Ad) account. This is the account which holds the data related to your Ads.

  • Manager account, also called Customer account. This account is used to manage the advertiser account(s) and other manager accounts. For example, any external agency you hire to manage your Microsoft Ads account would use this account.

Note: A Manager account can be linked to other Manager and Ad accounts in an infinite hierarchical setup.

Use Hevo’s Microsoft Ads connector to integrate all your Microsoft Ads accounts and replicate the account data into your Destination database or data warehouse for analysis.

Key steps of setting up Microsoft Ads as a Source in your Hevo Pipeline include authorizing Hevo to access the data and selecting the accounts and the objects and reports within these for replication. Read the sections below for details of these tasks.


  • An active Microsoft account with valid Microsoft Advertising user credentials.

  • Access to the accounts for which data is to be replicated.

Read Microsoft Advertising User Roles.

Configuring Microsoft Ads as a Source

Note: Disable all ad-blocking software to avoid issues during the setup, as Microsoft Advertising authentication process uses pop ups.

Perform the following steps to set up Microsoft Ads as the Source in your Pipeline:

  1. Click PIPELINES in the Asset Palette.

  2. Click + CREATE in the Pipelines List View.

  3. In the Select Source Type page, select Microsoft Advertising.

  4. In the Configure your Microsoft Ads Account page, click ADD MICROSOFT ADS ACCOUNT.

  5. Sign-in to your account and authorize Hevo to read your data.

  6. In the Configure your Microsoft Ads Source page, specify the following:

    configure Microsoft Ads as a Source

    • Pipeline Name: A unique name for the Pipeline, not exceeding 255 characters.

    • Select Objects & Reports: Select objects and reports which need to be replicated. By default, all objects and reports are replicated.

    • Select Accounts: Provide the authenticated Microsoft account credentials.

    • Core Objects: Select the Core Objects to be replicated. See section Core Objects below.

      Note: You must select at least one object.

    • Reports: Select the Reports you want to replicate for the selected objects. See section Reports below for the list of reports configured in Hevo.

      Note: You must select at least one report.

    • Select Accounts: Select the Microsoft Ads accounts whose data is to be replicated. See section Account Selection below.

  7. Click Continue to proceed with the subsequent steps of creating the Pipeline.

Authenticating Hevo on Microsoft Advertising using OAuth

Microsoft Ads uses the OAuth 2.0 protocol for authenticating the Bing Ads API, which is used to extract your Microsot Ads account data. From June 1st, 2022 onwards, to provide additional privacy and security, Microsoft Ads requires multi-factor authentication for all users who sign in via a third-party application that uses the Bing Ads API, such as Hevo. Download and install the Microsoft Authenticator app to set up multi-factor authentication for your Microsoft account, if it is not already set up.

Your Microsoft Ads account encapsulates permissions for all the objects and reports. You do not need to configure any additional permissions. Read User Roles and Permissions.

Account Selection

Hevo displays all your top level Manager accounts and the Ad accounts under these for selection. The intermediate sub-manager accounts are not displayed to simplify the account view and selection.

Note: In case an Ad account is linked to multiple top manager accounts, if you select the Ad account under one manager account but deselect it under another manager account, the Ad account is included for replication.

In addition:

  • Selecting an Ad account also selects its manager or top-level account. If you de-select the manager account, you are unable to select any of its Ad accounts.

  • Selecting a manager account automatically includes all Ad accounts within it for replication, even if these are added to the top manager account later. However, if you select individual Ad accounts, the Ad accounts added later to this manager account will not be automatically included in the current Pipeline.

  • If multiple Ad accounts are selected, data for all the selected accounts maps to the same table in your Destination. For example, if the accounts object is selected in two Ad accounts, data for both accounts is replicated into the accounts table. This is applicable to every object you select.

Core Objects

Microsoft Ads provides a variety of objects to hold your Ad campaign data, some of which may have a hierarchical structure. For example, Account → Campaigns → Ad Groups → Ads → Keywords associated with the Ad, and so on.

Select the objects you want to replicate. During ingestion of the data, the records in these objects are timestamped to avoid full ingestion every time.


Reports provide the metrics around users, their interaction related details, and the performance of your Ads . During replication, Hevo creates one report per object per account. You can replicate the following critical and popular Microsoft Ads reports. To integrate any other report apart from these, contact Hevo Support at

Report Name Description
Performance Reports Delivery performance reports show the overall effectiveness and cost of Ads and keywords for a specified time period.
Account Performance Report Provides data about long-term account performance and trends.
Ad Group Performance Report Provides data to compare delivery performance statistics by Ad group, campaign, or account attributes rather than at the keyword level.
Ad Performance Report Provides data that helps to determine which Ads lead to clicks and conversions, and which are not performing.
Audience Performance Report Provides comparison data for delivery performance statistics by audience, Ad group, campaign, or account attributes.
Campaign Performance Report Provides high-level performance statistics and quality attributes for each campaign or account.
Destination Url Performance Report Provides the list of landing pages that met audience expectations and potentially resulted in high click-through or conversion rates.
Keyword Performance Report Provides details of keywords that are performing well and those that are not.
Search Query Performance Report Provides information about what your audience is searching for when your Ads are shown.
Product Ad Reports Product Ad Reports offer a closer look at how your Microsoft Shopping Campaigns are performing based on product partition and product offer data.
Product Dimension Performance Report Provides aggregated performance data by product category, custom label, title, and type for a specified time period.
Product Partition Performance Report Provides aggregated performance data by product group and product partition type for a specified time period.
Product Search Query Performance Report Provides insight into what your audience is searching for when your Ads are shown as well as ensure that your product titles are relevant to search queries.
Targeting Reports Targeting Reports help you determine whether your Ads are reaching their intended audiences.
Age Gender Audience Report Provides data to help you discover how your campaigns and Ad groups are resonating with different age groups and genders.
Geographic Performance Report Provides details of where your traffic is coming from: the physical location of the people searching for your Ad or the locations people are searching for.
User Location Performance Report Provides details of where your traffic is coming from, broken out by the physical location and the location people are searching for.

For the complete list of reports offered by Microsoft Advertising and their detailed descriptions, read Report Types.

Source Considerations

Report Attributes and Performance Statistics

Report data includes both attributes and performance metrics data. By default, Hevo selects all report attributes and metrics for replication. However, in case of any conflict between these, Hevo replicates only the non-conflicting attributes and all the possible metrics data. For example, if a report includes impression share performance statistics metric columns, only the non-conflicting attributes along with all possible metrics are replicated. Read Column Restrictions for more information.

Reporting Data Retention Period

Microsoft Ads holds report data for a max of 36 months, and reports are aggregated on daily basis. Therefore, the Historical Load job fetches data for the past 36 months. Read Reporting Data Retention Period.

Data Completeness

Microsoft Ads report data is processed throughout the day and this data undergoing processing is considered as incomplete. It is usually considered complete at the end of the day, when Microsoft Ads has finished processing it.

The report Refresher jobs fetch past two days’ data every 24 hours to ensure that all of the data loaded is complete.

Rate Limits

Microsoft Advertising limits the number of API calls that Hevo can in a given time frame, or the rate at which Hevo can ingest the data. So depending on the API endpoint, Hevo may defer a job by a certain time as soon as the API limit is reached.

  • Core Objects jobs - deferred for 15 minutes.

  • Report jobs - deferred for 60 seconds.

Read Rate Limits.

Data Replication

Default Pipeline Frequency Minimum Pipeline Frequency Maximum Pipeline Frequency Custom Frequency Range (Hrs)
1 Hr 30 Mins 48 Hrs 1-48

Note: The custom frequency must be set in hours, as an integer value. For example, 1, 2, 3 but not 1.5 or 1.75.

Hevo Pipelines use Microsoft’s Bing Ads API to extract the data from your Microsoft Ads account. Different APIs within this API are used to fetch data from your Microsoft Ads account:

  • Core objects: fetched using the Bulk API.

  • Reports: fetched using the Reporting API.

  • Account: fetched using the Customer Management API.

Core Objects

For the core objects, the following jobs are run:

  • Historical: No historical jobs are run for objects as these mostly include informational data.

  • Incremental: Has the same frequency as the Pipeline. All core objects are fetched through Incremental jobs. The Account object’s data is fetched as a Full Load in each run of the job. The Bulk API ingests the core objects based on the timestamp. The ingestion position can be changed to up to 90 days from the current day.

Note: You can restart the job for core objects if you want to include the quality score data, as these fields are retrieved on every restart of the bulk job. The fields are keyword_relevance, landing_page_relevance, landing_page_user_experience and quality_score.


For each report, three jobs are run:

  • Historical: Runs once. Fetches data for 36 months in reverse chronological order, to fetch the most recent data first. Once the job finishes, its status changes to Historical Load Finished. The historical job’s position cannot be modified. This job can simply be restarted. Since it retrieves data in reverse order, the date offset displayed keeps moving backward as the job runs. Read Types of Data Synchronization.

  • Refresher: Runs daily. Fetches data for the last 2 days. This duration cannot be modified. The job checks for data in reverse order but it does not show any date offset. The job’s position cannot be changed. Upon completion, the job is deferred for 24 hours.

  • Incremental: Has the same frequency as the Pipeline. This job fetches data from the current day onwards. The position can be changed up to 36 months from the current day. This job cannot be restarted as it would always start fetching the data again for the current day.


  • Full Load: Fetches the entire account information data in each run of the Pipeline.

Schema and Primary Keys

Hevo uses the following schema to upload the records in the destination database:

Microsoft Ads ER Diagram

Data Model

The Report Models for all the reports replicated by Hevo are available here.


  • Not all Microsoft Ads objects and reports are replicated.

  • Sandbox accounts are not supported.

Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Jun-09-2022 NA Modified section, Authenticating Hevo on Microsoft Advertising using OAuth to add information about multi-factor authentication.
Oct-25-2021 NA Added the Pipeline frequency information in the Data Replication section.
Jul-26-2021 NA Added a note in the Overview section about Hevo providing a fully-managed Google BigQuery Destination for Pipelines created with this Source.
Last updated on 19 Aug 2022

Tell us what went wrong