{
  "openapi": "3.0.1",
  "info": {
    "title": "Apple Ads Library Scraper - App Store Ads Transparency",
    "description": "See every Apple Search Ads campaign on the App Store. Scrape Apple's Ad Repository by app or developer: creatives, placements, targeting, impression dates, locale variations & new-ad monitoring. The Apple side of your ads transparency stack.",
    "version": "0.1",
    "x-build-id": "txaA00zLicGTrd98G"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~apple-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-apple-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/scrapesage~apple-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-apple-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/scrapesage~apple-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-apple-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": {
          "searchQueries": {
            "title": "App or developer names",
            "type": "array",
            "description": "App or developer names to look up — e.g. \"Duolingo\", \"Spotify\", \"King\". Each name is resolved in Apple's Ad Repository register (apps + developers) and ALL their App Store ads are scraped.",
            "items": {
              "type": "string"
            }
          },
          "appIds": {
            "title": "App IDs",
            "type": "array",
            "description": "Exact App Store app IDs (the number in apps.apple.com/…/id123456789 URLs) — scrapes all their ads directly.",
            "items": {
              "type": "string"
            }
          },
          "developerIds": {
            "title": "Developer IDs",
            "type": "array",
            "description": "Exact App Store developer IDs (the number in apps.apple.com/…/developer/id123456 URLs) — scrapes ads of ALL that developer's apps.",
            "items": {
              "type": "string"
            }
          },
          "entitySearchQueries": {
            "title": "Advertiser directory search",
            "type": "array",
            "description": "Search the register of advertised apps & developers instead — emits one record per match (name, type, ID, ads count, sample ads). Great for building lists of apps actively running Apple Search Ads (e.g. \"vpn\", \"casino\", \"language\").",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "App Store URLs — app pages (apps.apple.com/us/app/…/id123) or developer pages (apps.apple.com/us/developer/…/id456) — or bare numeric IDs. Auto-detected and scraped.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries (EU)",
            "type": "array",
            "description": "Only ads delivered in these countries — ISO codes or names (e.g. \"DE\", \"France\"). Empty = all 25 covered EU countries. TIP: with countries as the ONLY input, the actor browses each country's whole ad feed.",
            "items": {
              "type": "string"
            }
          },
          "datePreset": {
            "title": "Date window",
            "enum": [
              "LAST_90_DAYS",
              "LAST_180_DAYS",
              "LAST_YEAR"
            ],
            "type": "string",
            "description": "Impression window the repository reports on (data is published with a ~7-day delay).",
            "default": "LAST_90_DAYS"
          },
          "placements": {
            "title": "Placements",
            "type": "array",
            "description": "Keep only ads in these App Store placements. Empty = all placements.",
            "items": {
              "type": "string",
              "enum": [
                "APPSTORE_SEARCH_RESULTS",
                "APPSTORE_SEARCH_TAB",
                "APPSTORE_TODAY_TAB",
                "APPSTORE_PRODUCT_PAGES"
              ],
              "enumTitles": [
                "Search results",
                "Search tab",
                "Today tab",
                "Product pages"
              ]
            }
          },
          "includeAdVariations": {
            "title": "Include ad variations (locale creatives)",
            "type": "boolean",
            "description": "Fetch each ad's variations: every language version (localized app name, subtitle, promotional text) with per-device creative assets, plus all app-icon variations (one extra request per ad).",
            "default": false
          },
          "includeEntityAdStats": {
            "title": "Directory: include ad stats",
            "type": "boolean",
            "description": "In advertiser-directory mode, probe each app/developer's ads to add adsCount + sample ads (one extra request per record).",
            "default": true
          },
          "includeRestrictions": {
            "title": "Include advertising restrictions",
            "type": "boolean",
            "description": "Also scrape Apple's advertising-restriction events (ads removed / accounts suspended, with reason, basis, affected placements & countries). Set this with no other input to get ONLY the restrictions feed.",
            "default": false
          },
          "restrictionActions": {
            "title": "Restriction actions",
            "type": "array",
            "description": "Which restriction actions to include. Empty = both.",
            "items": {
              "type": "string",
              "enum": [
                "ACTION_ADVERTISING_REMOVED",
                "ACTION_ACCOUNT_SUSPENDED"
              ],
              "enumTitles": [
                "Advertising removed",
                "Account suspended"
              ]
            }
          },
          "maxEntitiesPerQuery": {
            "title": "Max entities per name search",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "How many matching apps/developers to scrape per name in searchQueries.",
            "default": 3
          },
          "maxResults": {
            "title": "Max results (total)",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum records (ads + directory + restrictions) to return. 0 = no limit (explicit opt-in; pair with a run timeout).",
            "default": 100
          },
          "maxAdsPerQuery": {
            "title": "Max ads per query",
            "minimum": 0,
            "type": "integer",
            "description": "Per-app/per-country cap. 0 = no per-query cap (the repository itself stops paginating around ~1,100-1,300 records per query — use narrower countries to go deeper).",
            "default": 0
          },
          "monitorMode": {
            "title": "Monitor mode (only new / changed ads)",
            "type": "boolean",
            "description": "Track ads across runs in a key-value store and only output ads that are new or changed since the last run — perfect on an Apify Schedule for competitor new-ad alerts. Works alongside (not instead of) Apify Schedules: the Schedule triggers runs, monitor mode dedupes the output. Best with app/developer-scoped inputs and maxResults 0 so the full ad set is compared each run.",
            "default": false
          },
          "monitorStoreName": {
            "title": "Monitor store name",
            "type": "string",
            "description": "Named key-value store holding monitor state (lowercase letters, digits, hyphens). Use a different name per schedule if you run several monitors.",
            "default": "apple-ads-library-monitor"
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "The Ad Repository is an official open Apple API — default datacenter proxies work and are the cheapest. Switch to RESIDENTIAL only if you ever see blocked requests.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}