{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta Ads Library Scraper (Facebook Ads)",
    "description": "For creative strategists, copywriters, media buyers, marketers, and agencies. Scrape the Meta Ad Library by exact phrase, keyword, page, or Library URL. Control country, status, media type, platforms, dates, and impressions sort. $0.60 per 1,000 ads. No Facebook token.",
    "version": "0.2",
    "x-build-id": "tJbf7R72NjfbAaOlB"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sol-arkis~meta-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sol-arkis-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/sol-arkis~meta-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sol-arkis-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/sol-arkis~meta-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sol-arkis-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": {
          "keywords": {
            "title": "Search keywords",
            "type": "array",
            "description": "Keywords to search in the Ad Library, e.g. \"coffee\" or a brand name. Each keyword is one query. Use \"Search type\" to switch between any-word and exact-phrase matching.",
            "items": {
              "type": "string"
            }
          },
          "urls": {
            "title": "Ad Library or Facebook page URLs",
            "type": "array",
            "description": "Optional. Ad Library search URLs copied from your browser (facebook.com/ads/library/?...). Their filters (country, q, search_type, media_type, active_status, sort, start_date, view_all_page_id, id) are respected; missing filters fall back to the fields below. Also accepts Facebook page URLs (facebook.com/YourPage, profile.php?id=…), bare numeric page IDs (all ads by that page) and single-ad URLs (…/ads/library/?id=<adArchiveId>).",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "2-letter ISO country code the ads were shown in (e.g. SG, US, GB, DE, AU) or ALL for every country.",
            "default": "SG"
          },
          "activeStatus": {
            "title": "Ad status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Active ads only, inactive ads only, or both.",
            "default": "active"
          },
          "mediaType": {
            "title": "Media type",
            "enum": [
              "all",
              "image",
              "video",
              "meme",
              "none"
            ],
            "type": "string",
            "description": "Filter by creative type.",
            "default": "all"
          },
          "maxAds": {
            "title": "Max ads per query",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of unique ads to save for each keyword / URL. You pay per saved ad. Above 30 ads Meta needs to paginate — use a RESIDENTIAL proxy for that.",
            "default": 50
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "impressions",
              "most_recent"
            ],
            "type": "string",
            "description": "Order of results as on the Ad Library site.",
            "default": "impressions"
          },
          "searchType": {
            "title": "Search type",
            "enum": [
              "keyword_unordered",
              "keyword_exact_phrase"
            ],
            "type": "string",
            "description": "keyword_unordered matches ads containing all the words in any order; keyword_exact_phrase matches the exact phrase.",
            "default": "keyword_unordered"
          },
          "startDateMin": {
            "title": "Delivered after (inclusive)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Optional. Only include ads that delivered impressions on or after this date (YYYY-MM-DD). This is Meta's delivery window, not the ad creation date. Pasted Ad Library URLs that already set start_date[min] keep their own value."
          },
          "startDateMax": {
            "title": "Delivered before (inclusive)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Optional. Only include ads that delivered impressions on or before this date (YYYY-MM-DD). Use with Delivered after to bound a window. Pasted Ad Library URLs that already set start_date[max] keep their own value."
          },
          "publisherPlatforms": {
            "title": "Publisher platforms",
            "type": "array",
            "description": "Optional. Limit results to ads that ran on these surfaces. Leave empty for every platform Meta returns (Facebook, Instagram, Messenger, Audience Network, Threads). Pasted Ad Library URLs that already set publisher_platforms keep theirs.",
            "items": {
              "type": "string",
              "enum": [
                "facebook",
                "instagram",
                "messenger",
                "audience_network",
                "threads"
              ],
              "enumTitles": [
                "Facebook",
                "Instagram",
                "Messenger",
                "Audience Network",
                "Threads"
              ]
            }
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "monitor"
            ],
            "type": "string",
            "description": "search (default) saves every matching ad up to maxAds. monitor only writes ads whose adArchiveId was not stored for this query fingerprint (keywords, urls, country, status, media type, search type, delivery dates, platforms) in the named key-value store meta-ads-library-monitor. Schedule the same input to watch a page or keyword. The first run is the baseline: every ad it fetched is recorded as seen.",
            "default": "search"
          },
          "emitAdChanges": {
            "title": "Emit ad changes (monitor)",
            "type": "boolean",
            "description": "Only used when Mode is monitor. Snapshot primary text, headline, CTA, landing URL, media URLs, active status, platforms, and start/end dates. When a previously seen ad comes back with a different snapshot, write an itemType: ad-change row (charged as ad-change). The first run only stores snapshots; it does not emit or charge changes. New ads are still charged as ad.",
            "default": false
          },
          "saveMedia": {
            "title": "Save creatives to durable storage",
            "type": "boolean",
            "description": "Optional paid add-on, off by default. Download each ad's images and videos (HD preferred) plus video preview stills into this run's key-value store, and add savedMedia, savedImageUrls and savedVideoUrls with durable Apify URLs. Original Meta CDN URLs stay on the item; they expire in about 1-4 days. Charged once per ad that had at least one file saved (media-save). Failed downloads are skipped and do not fail the run.",
            "default": false
          },
          "scrapeAdDetails": {
            "title": "Fetch ad details (payer, beneficiary, EU reach)",
            "type": "boolean",
            "description": "Makes one extra request per ad to Meta's ad-details endpoint to add payer, beneficiary, EU total reach / audience (age, gender, locations), Instagram account and page verification. Fails soft: if Meta refuses, ads are still saved without these fields. Turn off for faster runs.",
            "default": true
          },
          "includeRaw": {
            "title": "Include raw Meta data",
            "type": "boolean",
            "description": "Adds a \"raw\" field with the unmodified Ad Library objects (search result + details). Makes items much larger.",
            "default": false
          },
          "paginationFallback": {
            "title": "Fallback when pagination is blocked",
            "type": "boolean",
            "description": "If Meta throttles cursor pagination (\"Rate limit exceeded\"), keep collecting ads by re-running the first results page over narrower slices of your search (content language, media type, platform, past months, alternate sort). All ads still match your filters, but the extra ones are not in the selected sort order and coverage of very large result sets is partial.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify Proxy is on by default. Choose the RESIDENTIAL group when maxAds is above 30 — Meta rate-limits Ad Library pagination from datacenter IPs and may show a login wall.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}