{
  "openapi": "3.0.1",
  "info": {
    "title": "Microsoft Ads Library Scraper - Competitor Ads",
    "description": "Scrape the Microsoft Ads Library, the public EU archive of ads shown on Bing and the Microsoft Advertising Network, by keyword, advertiser or ad id. One row per distinct ad, charged once: ad copy, landing URL, first and last shown, impressions, countries, payer, targeting. JSON, CSV, API.",
    "version": "0.1",
    "x-build-id": "Y8fcvqWLz7RGOUiA6"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/automation_craft~microsoft-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-automation_craft-microsoft-ads-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/automation_craft~microsoft-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-automation_craft-microsoft-ads-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/automation_craft~microsoft-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-automation_craft-microsoft-ads-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "One keyword or phrase per line, searched in the ad text; every word of a term must appear in the ad. Each term is one search; a term the archive has no ad for costs nothing and comes back as a free coverage row. The archive's search accepts unaccented Latin letters, digits, spaces and # $ & ' * - . ? @ ^ _ | only: a term with other characters (an umlaut, a comma, quotes) is not searched and comes back as a free row. Up to 200 terms per run.",
            "items": {
              "type": "string"
            }
          },
          "advertisers": {
            "title": "Advertisers",
            "type": "array",
            "description": "One advertiser per line: a name (eBay Marketplaces GmbH), an advertiser id (4295009683) or an advertiser page URL of the library (https://adlibrary.ads.microsoft.com/advertiser/4295009683). A name is looked up in the archive's advertiser register and every entry with exactly that name is searched (one company often has several advertiser accounts); a free row lists the entries used. A name the register does not have costs nothing and comes back as a free row with the closest register names. Up to 200 per run.",
            "items": {
              "type": "string"
            }
          },
          "advertiserMatch": {
            "title": "Advertiser name matching",
            "enum": [
              "exact",
              "contains"
            ],
            "type": "string",
            "description": "exact: the register name must equal your text (capitals and spacing do not matter, accents do). contains: every register entry whose name contains your text is searched, up to 24 per text. Through the API send exact or contains. When the field is left out, exact is used."
          },
          "searchTermsWithinAdvertisers": {
            "title": "Search the terms inside the advertisers' ads",
            "type": "boolean",
            "description": "With search terms and advertisers both given: on, every term is searched inside each advertiser's ads only (ads of eBay that mention shoes); off, terms and advertisers are separate searches. Off when the field is left out."
          },
          "adIds": {
            "title": "Ad ids or ad page URLs",
            "type": "array",
            "description": "One per line: an ad id (72361740039047) or an ad page URL of the library (https://adlibrary.ads.microsoft.com/ad/72361740039047). Each ad found comes back as one row with its detail record and is charged as one Ad detail record. An id the archive does not have costs nothing and comes back as a free row. Pass long ids as text. Up to 5,000 per run.",
            "items": {
              "type": "string"
            }
          },
          "advertiserSearchTerms": {
            "title": "Advertiser register search",
            "type": "array",
            "description": "Search the advertiser register itself instead of ads: one text per line returns advertiser rows (name, id, country, verified status) for every register name containing it. Advertiser rows are not charged one by one; each page of up to 24 register results read costs one Results page. Up to 50 texts per run.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "uniqueItems": true,
            "type": "array",
            "description": "Keep ads that were shown in at least one of these countries. Leave empty for every country of the archive (EU 27 plus Iceland, Liechtenstein and Norway). Several countries are one search, not one search per country. Note: the archive counts any impression, so an ad shown almost only in Germany also matches France; the share per country is in the detail record.",
            "items": {
              "type": "string",
              "enum": [
                "AT",
                "BE",
                "BG",
                "HR",
                "CY",
                "CZ",
                "DK",
                "EE",
                "FI",
                "FR",
                "DE",
                "GR",
                "HU",
                "IS",
                "IE",
                "IT",
                "LV",
                "LI",
                "LT",
                "LU",
                "MT",
                "NL",
                "NO",
                "PL",
                "PT",
                "RO",
                "SK",
                "SI",
                "ES",
                "SE"
              ],
              "enumTitles": [
                "Austria (AT)",
                "Belgium (BE)",
                "Bulgaria (BG)",
                "Croatia (HR)",
                "Cyprus (CY)",
                "Czechia (CZ)",
                "Denmark (DK)",
                "Estonia (EE)",
                "Finland (FI)",
                "France (FR)",
                "Germany (DE)",
                "Greece (GR)",
                "Hungary (HU)",
                "Iceland (IS)",
                "Ireland (IE)",
                "Italy (IT)",
                "Latvia (LV)",
                "Liechtenstein (LI)",
                "Lithuania (LT)",
                "Luxembourg (LU)",
                "Malta (MT)",
                "Netherlands (NL)",
                "Norway (NO)",
                "Poland (PL)",
                "Portugal (PT)",
                "Romania (RO)",
                "Slovakia (SK)",
                "Slovenia (SI)",
                "Spain (ES)",
                "Sweden (SE)"
              ]
            }
          },
          "startDate": {
            "title": "Shown from",
            "type": "string",
            "description": "First day of the window: YYYY-MM-DD, or a number of days, weeks or months back from the end date, such as 30 days. An ad is returned when it was shown on at least one day of the window. When the field is left out, the window starts 30 days before the end date. For the whole archive send 2023-06-01 (the archive records ads since June 2023). A shorter window is also the way to read a large search completely: the archive answers at most 1,000 results per search."
          },
          "endDate": {
            "title": "Shown until",
            "type": "string",
            "description": "Last day of the window: YYYY-MM-DD, today or yesterday. Today when the field is left out."
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "all",
              "text",
              "image"
            ],
            "type": "string",
            "description": "all: every ad. text: only ads without an image asset (classic text ads). image: only ads with at least one image asset. The filter is applied to the results the archive returns, so the pages read are the same. Through the API send all, text or image; all when the field is left out."
          },
          "includeDetails": {
            "title": "Include the detail record of every ad",
            "type": "boolean",
            "description": "Adds to every ad who paid for it, the first and last day shown, the total impressions band (with numeric minimum and maximum), the impression share per country and the targeting types used. One more request per ad and one Ad detail record charged per ad whose record was read. Off when the field is left out."
          },
          "includeAdvertiserProfile": {
            "title": "Include the advertiser's country and verified status",
            "type": "boolean",
            "description": "Adds advertiserCountry and advertiserVerified from the advertiser register to every ad (one request per distinct advertiser in the run, no extra charge). Off when the field is left out."
          },
          "deepSearch": {
            "title": "Deep search: split searches the archive caps",
            "type": "boolean",
            "description": "The archive answers at most 1,000 results per search, of which about 560 are different ads. With deep search on, a search that hits this cap is cut into two halves of its date window, again and again down to single days, and every part is read. Mid size searches come back complete this way; the coverage row says for each search whether any part was still capped. More Results pages are read and charged. Off when the field is left out."
          },
          "maxAds": {
            "title": "Maximum ads per run",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "The run stops when this many ads were delivered. 100 when the field is left out; up to 100,000."
          },
          "maxAdsPerSearch": {
            "title": "Maximum ads per search",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "A cap for each search term and each advertiser. 0 or empty: no cap per search."
          },
          "maxPagesPerSearch": {
            "title": "Maximum Results pages per search",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "A search stops after reading this many pages of 24 results. One search without deep search reads at most 42 pages; a deep search of a very large query can read many more. 400 when the field is left out; up to 5,000."
          },
          "maxAdvertisersPerTerm": {
            "title": "Maximum advertisers per register search",
            "minimum": 1,
            "maximum": 240,
            "type": "integer",
            "description": "For the advertiser register search: advertiser rows per text. 24 when the field is left out (one page); up to 240."
          },
          "memoryName": {
            "title": "Memory name (only new ads on later runs)",
            "type": "string",
            "description": "A plain name, for example competitor watch. Ads delivered under this name are remembered in a key value store this Actor creates in your account; later runs with the same name skip them free and deliver only new ads. The pages read to find them are still charged as Results pages. A memory belongs to this Actor and to your account. If the memory cannot be opened, locked or saved, the run delivers its ads free."
          },
          "resetMemory": {
            "title": "Reset this memory first",
            "type": "boolean",
            "description": "Forget everything stored under the memory name before the run, so every ad counts as new again."
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Not needed: the Ad Library API answers the run's own address. If you set a proxy, the run keeps one address for the whole run; the residential group is replaced by the datacenter pool."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}