# Microsoft Ad Library Scraper — Bing Ads Transparency (DSA) (`rastriq/microsoft-ad-library-scraper`) Actor

Scrape the Microsoft Advertising Ad Library (Bing ads shown in the EU/EEA): ad text, landing pages, images, who paid, delivery dates, impressions and share per country, targeting types. Splits searches automatically past the 1,000-result limit.

- **URL**: https://apify.com/rastriq/microsoft-ad-library-scraper.md
- **Developed by:** [Rastriq — Structured data from the world](https://apify.com/rastriq) (community)
- **Categories:** SEO tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Microsoft Ad Library Scraper — Bing Ads Transparency (DSA)

**Microsoft Ad Library Scraper** extracts ads from the official [Microsoft Advertising Ad Library](https://adlibrary.ads.microsoft.com/), the repository of Bing search ads shown in the EU and EEA under the Digital Services Act: ad text, landing page, images and, with details, who paid, delivery dates, total impressions, impression share per country and targeting types. Use it as a Bing Ads Library API for competitor research, paid-search monitoring and DSA transparency analysis.

### 🔎 What is Microsoft Ad Library Scraper?

Microsoft's Ad Library API stops at **1,000 results per search** and gives payer, dates and impressions only one ad at a time, behind a strict rate limit. **Microsoft Ad Library Scraper** handles both:

- ✂️ **Past the 1,000-result limit** — a search that hits the limit is split by country, then by date down to single days, and the slices are merged without duplicates
- 🏢 **Search by advertiser name or id** — `Decathlon` finds every Decathlon account (France, Spain, Germany…) by whole-word match
- 🔍 **Search by ad text** — any advertiser using a word (`vpn`, `zapatillas`) in their ads
- 🧾 **Full details** — paid for by, first and last shown, impressions range, share per country, targeting types (with exclusions)
- 🛡️ **Stable on Microsoft's rate limit** — adaptive pacing and automatic recovery from Azure Front Door blocks
- 🌍 **EU + EEA** — 27 EU countries plus Iceland, Liechtenstein and Norway
- ✅ **Data quality** — `quality_flags`, a DSA art. 39 coverage score and a flag on slices that could not be completed

Typical uses: tracking competitors' Bing search ads and landing pages, finding which agency pays for a brand's campaigns, impression benchmarks by country, and compliance research.

### 📦 What data does Microsoft Ad Library Scraper extract?

Every row has the common block shared by all Rastriq ad-library scrapers plus **every field Microsoft publishes, with Microsoft's original names**.

| Group | Fields |
|---|---|
| 🆔 Identity | `platform`, `ad_id`, `source_url`, `scraped_at` (+ `AdId`, `AdvertiserId`) |
| 🏢 Advertiser | `advertiser`, `payer` (+ `AdvertiserName`, `AdDetails.PaidForByName`) |
| 🎨 Content | `Title`, `Description`, `DisplayUrl`, `destination_url`, `creative_urls`, `assets` (+ `AssetJson`) |
| 📅 Period | `first_shown`, `last_shown` (+ `AdDetails.StartDate`, `AdDetails.EndDate`) |
| 👁️ Impressions | `reach_min`, `reach_max`, `impression_share_by_country`, `reach_by_country`, `countries` (+ `AdDetails.TotalImpressionsRange`, `AdDetails.ImpressionsByCountry`) |
| 🎯 Targeting | `targeting_types` (+ `AdDetails.Targets`) |
| ✅ Quality | `details_status`, `quality_flags[]`, `art39_coverage`, `is_natural_person_suspected` |
| 🔁 Traceability | `query_advertiser_id`, `query_search_text`, `query_country`, `query_start_date`, `query_end_date` |

#### 📄 Flat table or nested JSON

By default every row is a **flat table** — one value per column, ready for Excel, Google Sheets or CSV: lists become comma-separated text (URLs are separated by `|`), reach per country becomes `reach_min_<CC>` / `reach_max_<CC>` columns, and the DSA art. 39 score becomes `art39_covered`, `art39_total`, `art39_ratio` and `art39_missing`. Set **Output format** to *Nested JSON* to keep the source's original objects and lists for programmatic use.

### 🚀 How to use Microsoft Ad Library Scraper

1. Open **Microsoft Ad Library Scraper** in Apify Console and click **Try for free**.
2. Add **Advertisers** (`Decathlon`, `Nike` or a numeric advertiser id) and/or **Search terms**.
3. Pick the period and, optionally, the **Countries**.
4. Keep **Fetch details** on for payer, dates and impressions, or turn it off for a fast list.
5. Set **Max ads** (50 for a first test), click **Start**, and export as JSON, CSV or Excel.

### ⚙️ Input parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `advertisers` | array | — | Names (whole-word match) or numeric advertiser ids |
| `searchTerms` | array | — | Words in the ad text, any advertiser |
| `maxItems` | integer | `1000` | Max ads in the run (0 = no limit) |
| `startDate` / `endDate` | string | `30 days` / today | Ads active in the period |
| `countries` | array | all | ISO codes: EU-27 + `IS`, `LI`, `NO` |
| `fetchDetails` | boolean | `true` | Payer, dates, impressions, share per country, targeting |
| `maxDetails` | integer | `0` | Details for the first N ads only (0 = all) |
| `advertiserMatch` | string | `word` | `word`, `contains`, `exact`, `any` |
| `splitLargeQueries` | boolean | `true` | Split searches that hit the 1,000 limit |
| `hashPersonalNames` | boolean | `false` | Pseudonymise names flagged as private individuals |
| `outputFormat` | string | `flat` | `flat` (one column per value) or `nested` (original JSON structure) |

```json
{
  "advertisers": ["Decathlon"],
  "countries": ["ES", "FR"],
  "startDate": "2026-10-01",
  "fetchDetails": true,
  "maxItems": 200
}
```

### 📤 Output example

One row of the default flat output (selected columns):

```json
{
  "platform": "microsoft",
  "ad_id": "79577362149432",
  "advertiser": "Société Decathlon France S.A.S",
  "payer": null,
  "first_shown": "2023-10-03",
  "last_shown": "2026-11-10",
  "reach_min": 10000000,
  "reach_max": 25000000,
  "reach_min_FR": 10000000,
  "reach_max_FR": 25000000,
  "impression_share_FR": 1.0,
  "impression_share_BE": 0.0,
  "countries": "FR",
  "targeting_types": "Location (exclusion), MicrosoftAudiences, AdvertiserAudiences",
  "destination_url": "https://www.decathlon.fr/tous-les-sports/tennis-de-table/tables-outdoor-exterieur",
  "source_url": "https://adlibrary.ads.microsoft.com/ad/79577362149432",
  "Title": "C'est le moment de s'équiper - Produits éco-conçus* - Retrait 1h en magasin",
  "Description": "Tennis-de-table - Table : votre produit de sport au prix juste sur decathlon.fr. Le divertissement est à po…",
  "AdDetails_TotalImpressionsRange": "10M - 25M",
  "details_status": "ok",
  "quality_flags": "reach_is_impressions, reach_by_country_estimated_from_share, payer_not_disclosed, possibly_still_running",
  "art39_ratio": 0.857,
  "art39_missing": "payer",
  "scraped_at": "2026-11-11T16:42:02Z"
}
```

…plus `reach_min_<CC>` / `reach_max_<CC>` and `impression_share_<CC>` for every country, the other `AdDetails_*` columns and every field Microsoft publishes.

Good to know: Microsoft publishes **impressions**, not reach — `reach_min`/`reach_max` hold the impressions range (flag `reach_is_impressions`), and `reach_by_country` is that range multiplied by the published share (flag `reach_by_country_estimated_from_share`). `PaidForByName` is often empty (`payer_not_disclosed`).

### 💰 How much does it cost to scrape the Microsoft Ad Library?

Microsoft Ad Library Scraper uses pay-per-event pricing with volume discounts by Apify plan. You pay per ad delivered, plus a separate event when its details are fetched. Duplicates found in several slices are free.

| Apify plan | Per 1,000 ads | Per 1,000 ads with details (extra) | Run start |
|---|---|---|---|
| Free | $0.50 | $2.00 | $0.002 |
| Starter (Bronze) | $0.45 | $1.75 | $0.002 |
| Scale (Silver) | $0.40 | $1.50 | $0.0015 |
| Business (Gold) | $0.35 | $1.25 | $0.001 |

- **Free plan ($5 credit)**: ~10,000 ads without details, or ~2,000 with details
- **Speed**: ~450 ads/minute without details (24 per request, one request every ~3 s). Details are rate-limited by Microsoft: about 3–5 per minute (≈150–300 per hour)

> 💡 **Tip**: get the list without details first, then run details with **Max ads with details** on the ads you care about.

### 🔗 Related Actors

Build a cross-platform view of competitor advertising with the Rastriq ad intelligence suite:

- [Google Ads Transparency Center Scraper](https://apify.com/Rastriq/google-ads-scraper) — Search, YouTube and Display ads
- [Facebook Ad Library Scraper](https://apify.com/Rastriq/fb-adlibrary-scraper) — Meta ads (Facebook & Instagram)
- [LinkedIn Ad Library Scraper](https://apify.com/Rastriq/linkedin-ad-library-scraper) — B2B ads on LinkedIn
- [TikTok Ad Library Scraper](https://apify.com/Rastriq/tiktok-ad-library-scraper) — TikTok ads, targeting and reach
- [X (Twitter) Ads Library Scraper](https://apify.com/Rastriq/x-ads-repository-scraper) — X ads in the EU

All of them share the same base fields (`platform`, `ad_id`, `advertiser`, `payer`, `first_shown`, `reach_by_country`…), so their datasets stack in one table.

### ❓ FAQ

**Which ads are included?** Bing/Microsoft Advertising ads shown in the EU and EEA, which is what Microsoft publishes under the DSA, including ads that started before your period but were still active in it.

**How does it get past the 1,000-result limit?** Each search that reports 1,000 results is split by country, then by date down to single days. Only a slice that still has 1,000+ ads in one country on one day stays incomplete: its ads carry `slice_truncated_at_1000`, and the run summary (`OUTPUT`) lists the slice.

**Why are details slow?** Microsoft returns payer, dates and impressions only one ad at a time and blocks bursts of requests. Microsoft Ad Library Scraper paces itself (about 3–5 per minute) and recovers automatically from blocks, so runs finish instead of failing.

**Why does an ad found with country "BE" show 100 % of impressions in France?** The country filter is Microsoft's; it can return ads whose impressions fall mostly elsewhere. `impression_share_by_country` shows where the ad was actually seen.

**Does it collect personal data?** A few advertiser accounts belong to private individuals. Microsoft Ad Library Scraper flags those rows with `is_natural_person_suspected` and can pseudonymise the names (`hashPersonalNames`). You are responsible for processing the data lawfully (GDPR).

**Is it legal to scrape the Microsoft Ad Library?** The Actor reads Microsoft's public, documented and anonymous Ad Library API at a moderate rate. You are responsible for complying with Microsoft's terms and applicable laws in how you use the data.

**Something broke?** Open an issue in the Actor's **Issues** tab — we usually reply within 24 hours.

# Changelog

This Actor's version history is a separate document: https://apify.com/rastriq/microsoft-ad-library-scraper/changelog.md

# Actor input Schema

## `advertisers` (type: `array`):

Advertiser names or Microsoft advertiser ids (the number in <code>adlibrary.ads.microsoft.com/advertiser/\<id></code>).<br><br>A name is looked up in the library; every account whose name contains it as a whole word is scraped (e.g. <code>Decathlon</code> → Decathlon France, Spain, Germany…). Use <b>Advertiser name match</b> to change that.

## `searchTerms` (type: `array`):

Words that appear in the ad text, for any advertiser (e.g. <code>zapatillas</code>, <code>vpn</code>). Combine with <b>Countries</b> to keep it focused.

## `maxItems` (type: `integer`):

Maximum ads in the dataset for the whole run. 0 = no limit.

## `startDate` (type: `string`):

Ads <b>active at any time</b> in the period, including ads that started earlier. Absolute (<code>2026-01-01</code>) or relative (<code>30 days</code>).

## `endDate` (type: `string`):

End of the period. Empty = today.

## `countries` (type: `array`):

Countries where the ads were shown (EU + Iceland, Liechtenstein, Norway). Empty = all.

## `fetchDetails` (type: `boolean`):

Add <b>paid for by</b>, start/end date, total impressions range, impression share per country and targeting types. One extra request per ad; Microsoft allows about <b>3–5 per minute</b>, so 100 ads with details take ~20–35 min. Charged per ad with details.<br><br>Turn off for a fast list of ads (text, landing page, images).

## `maxDetails` (type: `integer`):

Fetch details for the first N ads only; the rest are delivered without them (flag <code>details_skipped_limit</code>). 0 = all.

## `advertiserMatch` (type: `string`):

How a name in <b>Advertisers</b> is matched against the library's accounts. <b>Whole word</b> keeps <i>Nike - EMEA</i> for <code>Nike</code> but not <i>…Steinike</i>.

## `splitLargeQueries` (type: `boolean`):

Microsoft returns at most 1,000 ads per search. When a search hits that limit it is split by country, then by date down to single days. A slice still over 1,000 is flagged <code>slice_truncated_at_1000</code>. Off = take the first 1,000 only.

## `outputFormat` (type: `string`):

<b>Flat</b> (default): every value in its own column — lists become comma-separated text, reach per country becomes <code>reach_min_DE</code> / <code>reach_max_DE</code> columns, and art. 39 coverage becomes <code>art39_ratio</code> / <code>art39_missing</code>.<br><br><b>Nested</b>: keeps the source's original objects and lists (e.g. the full per-language variations or per-country breakdown) for programmatic use.

## `hashPersonalNames` (type: `boolean`):

Some advertisers are private individuals (sole traders). Every such row is flagged <code>is_natural_person_suspected</code>; turn this on to replace those names with a stable SHA-256 pseudonym.

## `proxyConfiguration` (type: `object`):

Not needed normally.

## `listIntervalSec` (type: `integer`):

Raised automatically after a block (Azure Front Door), lowered again after successes.

## `detailIntervalSec` (type: `integer`):

Microsoft blocks bursts of detail requests; 12 s keeps a run steady. Adjusted automatically.

## `maxRetries` (type: `integer`):

Retries after a block or a 5xx, with exponential backoff (15–90 s).

## Actor input object example

```json
{
  "advertisers": [
    "Decathlon"
  ],
  "maxItems": 20,
  "startDate": "7 days",
  "fetchDetails": true,
  "maxDetails": 5,
  "advertiserMatch": "word",
  "splitLargeQueries": true,
  "outputFormat": "flat",
  "hashPersonalNames": false,
  "listIntervalSec": 3,
  "detailIntervalSec": 12,
  "maxRetries": 5
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `reach` (type: `string`):

No description

## `creatives` (type: `string`):

No description

## `compliance` (type: `string`):

No description

## `allFields` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "advertisers": [
        "Decathlon"
    ],
    "maxItems": 20,
    "startDate": "7 days",
    "maxDetails": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("rastriq/microsoft-ad-library-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "advertisers": ["Decathlon"],
    "maxItems": 20,
    "startDate": "7 days",
    "maxDetails": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("rastriq/microsoft-ad-library-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "advertisers": [
    "Decathlon"
  ],
  "maxItems": 20,
  "startDate": "7 days",
  "maxDetails": 5
}' |
apify call rastriq/microsoft-ad-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rastriq/microsoft-ad-library-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/HtelAOjEJWYRhmZw1/builds/6w1xVuzfozkTBzSKY/openapi.json
