Microsoft Ads

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.


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.

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.

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 Replication Schedule

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 Historical Loads.

  • 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.

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.


  • Not all Microsoft Ads objects and reports are replicated.
  • Sandbox accounts are not supported.


  • 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.

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.

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.

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 a Source for your Hevo Pipeline:

  1. Click the Pipelines icon in the Asset Palette.

  2. In the Pipelines List View, click CREATE PIPELINE.

  3. Select Microsoft Advertising as the Source.

  4. In the Configure Your Microsoft Ads Source page, click Add Microsoft Ads Account.

  5. In the Configure Your Source page:

    configure Microsoft Ads as a Source

    1. Provide the authenticated Microsoft account credentials.
    2. Select the Core Objects to be replicated. See section Core Objects below. Note: You must select at least one object.
    3. 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.
    4. Select the Microsoft Ads accounts whose data is to be replicated. See section Account Selection below.
  6. Click Continue to proceed with the subsequent steps of creating the Pipeline.

Data Model

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

Microsoft Ads ER Diagram

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

Last updated on 01 Sep 2020