{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook/Meta Ads Library Scraper API $0.5/1k",
    "description": "⚡ Fast & Cheap ($0.50/1k): Scrape Facebook & Instagram Ads Library by keyword, Page URL, @handle or Ad ID in seconds. Extracts HD videos, winning ads, CTAs, EU/UK reach & spend.",
    "version": "1.0",
    "x-build-id": "5xrlhSR6sT7JcQdoY"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/unitbytes~meta-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-unitbytes-meta-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/unitbytes~meta-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-unitbytes-meta-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/unitbytes~meta-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-unitbytes-meta-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": {
          "queries": {
            "title": "Search Keywords or Brand Names",
            "maxItems": 50,
            "type": "array",
            "description": "Keywords, phrases, or brand names to search in Meta Ad Library (e.g. 'Nike', 'AI CRM software', 'Shopify'). Up to 50 queries per run. Ignored automatically if you paste URLs or IDs below without changing the prefill.",
            "items": {
              "type": "string"
            }
          },
          "urls": {
            "title": "Facebook Page URLs, Ad Library URLs, or Instagram URLs",
            "maxItems": 25,
            "type": "array",
            "description": "Paste any Meta Ad Library search/page URL (`facebook.com/ads/library/?...`), Facebook Page URL (`https://www.facebook.com/shopify`), or Instagram profile URL (`https://www.instagram.com/gymshark/`). Up to 25 URLs/handles per run.",
            "items": {
              "type": "string"
            }
          },
          "instagramHandles": {
            "title": "Instagram Handles (Optional)",
            "maxItems": 25,
            "type": "array",
            "description": "Instagram advertiser handles (e.g. `@gymshark` or `loungebyzalando`) to resolve and extract all linked Instagram & Facebook ads (up to 25 URLs/handles per run).",
            "items": {
              "type": "string"
            }
          },
          "adIds": {
            "title": "Direct Ad Archive IDs (Optional)",
            "maxItems": 50,
            "type": "array",
            "description": "Specific numeric Meta Ad Archive IDs (e.g. `1703932024036039`) to look up directly (up to 50 queries/IDs per run).",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Target Country (ISO Code or 'ALL')",
            "type": "string",
            "description": "2-letter ISO country code (`US`, `DE`, `GB`, `FR`, `CA`, `AU`, `BR`) or `ALL` for worldwide ads. Use EU countries (`DE`, `FR`, `NL`, `AT`, `ES`, `IT`) or `GB` (`UK`) to populate total reach & age/gender demographics.",
            "default": "US"
          },
          "activeStatus": {
            "title": "Active Status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Filter ads by delivery status in Meta Ad Library.",
            "default": "active"
          },
          "adType": {
            "title": "Ad Category",
            "enum": [
              "all",
              "political_and_issue_ads",
              "housing_ads",
              "employment_ads",
              "credit_ads"
            ],
            "type": "string",
            "description": "Filter by Meta Ad Library category. Select 'Issues, Elections or Politics' for spend & impression ranges.",
            "default": "all"
          },
          "mediaType": {
            "title": "Creative Media Format",
            "enum": [
              "all",
              "video",
              "image",
              "meme",
              "none"
            ],
            "type": "string",
            "description": "Filter ads by creative media type on Meta's server.",
            "default": "all"
          },
          "publisherPlatforms": {
            "title": "Publisher Placements (Optional)",
            "type": "array",
            "description": "Restrict results to specific Meta placements (`facebook`, `instagram`, `audience_network`, `messenger`, `threads`, `whatsapp`). Leave empty for all placements.",
            "items": {
              "type": "string"
            }
          },
          "searchType": {
            "title": "Keyword Match Mode",
            "enum": [
              "keyword_unordered",
              "keyword_exact_phrase"
            ],
            "type": "string",
            "description": "Match words in any order (`keyword_unordered`) or match the exact phrase (`keyword_exact_phrase`).",
            "default": "keyword_unordered"
          },
          "sortBy": {
            "title": "Sort Order",
            "enum": [
              "default",
              "impressions",
              "relevancy"
            ],
            "type": "string",
            "description": "Native Meta Ad Library server-side sort order.",
            "default": "default"
          },
          "startDateMin": {
            "title": "Active Window From (YYYY-MM-DD)",
            "type": "string",
            "description": "Matches Meta Ad Library's native date filter (`start_date[min]`): returns ads that were active on or after this date (e.g. `2026-01-01`)."
          },
          "startDateMax": {
            "title": "Active Window Until (YYYY-MM-DD)",
            "type": "string",
            "description": "Matches Meta Ad Library's native date filter (`start_date[max]`): returns ads started on or before this date (e.g. `2026-12-31`)."
          },
          "contentLanguages": {
            "title": "Ad Languages (ISO Codes, Optional)",
            "type": "array",
            "description": "Filter ads by detected language ISO code (e.g. `en`, `de`, `es`, `fr`).",
            "items": {
              "type": "string"
            }
          },
          "scrapeAdDetails": {
            "title": "Include Full Advertiser, IG & EU/UK Transparency Details",
            "type": "boolean",
            "description": "Enriches ads with linked Instagram handle & followers, Page bio/category/likes, payer/beneficiary disclosures, and EU/UK total reach & age/gender/country breakdowns.",
            "default": true
          },
          "enableChangeTracking": {
            "title": "Enable Cross-Run Change Tracking (Baseline / New / Continuing)",
            "type": "boolean",
            "description": "Tracks advertiser ad Archive IDs across scheduled runs in a persistent Key-Value Store (`AD_MONITOR_STATE`) to label `monitorStatus` as `baseline` (first run), `new`, or `continuing`.",
            "default": false
          },
          "monitorStoreName": {
            "title": "Named Key-Value Store for Scheduled Monitoring (Optional)",
            "type": "string",
            "description": "Persistent Named Key-Value Store name (defaults automatically to `meta-ads-monitor-state` on Apify Cloud when change tracking is enabled)."
          },
          "maxItems": {
            "title": "Maximum Ads to Scrape",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Maximum total ads to return across this run.",
            "default": 20
          },
          "resumptionToken": {
            "title": "Resumption Token (Multi-Batch Pagination)",
            "type": "string",
            "description": "Paste `resumptionToken` from `RESUMPTION_TOKEN` in Key-Value Store to resume large runs from the exact cursor with zero duplicate ads."
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Apify Residential Proxy is automatically configured on cloud runs for reliable global delivery.",
            "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
                  },
                  "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}