{
  "openapi": "3.0.1",
  "info": {
    "title": "META ADS LYBRRYA SRAPPER (Cost-Optimized)",
    "description": "Low-cost Meta Ads Library scraper for competitor research. Uses the official Meta Ads Archive API first with no proxy, exports public ad links, page names, ad copy, dates, platforms, spend and impression fields, and supports n8n or spreadsheet workflows.",
    "version": "1.0",
    "x-build-id": "lwDCtluG8QLVxAazy"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/defensible_jadeite~meta-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-defensible_jadeite-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/defensible_jadeite~meta-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-defensible_jadeite-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/defensible_jadeite~meta-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-defensible_jadeite-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": {
          "searchTerms": {
            "title": "Search terms",
            "type": "string",
            "description": "Keywords to search in ads"
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Country codes e.g. ['DZ', 'FR', 'MA']",
            "default": [
              "DZ"
            ]
          },
          "maxResults": {
            "title": "Max results",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Maximum number of unique ads to save.",
            "default": 200
          },
          "activeOnly": {
            "title": "Active ads only",
            "type": "boolean",
            "description": "Ask the official Meta API for active ads only before results are returned.",
            "default": true
          },
          "activeLastDays": {
            "title": "Active in last N days",
            "minimum": 1,
            "maximum": 365,
            "type": "integer",
            "description": "Pre-filter by delivery start date before fetching results. Example: 60 means ads launched in the last 60 days.",
            "default": 60
          },
          "adDeliveryDateMin": {
            "title": "Delivery date min",
            "type": "string",
            "description": "Optional exact Meta API ad_delivery_date_min in YYYY-MM-DD format. Overrides Active in last N days when provided."
          },
          "adDeliveryDateMax": {
            "title": "Delivery date max",
            "type": "string",
            "description": "Optional exact Meta API ad_delivery_date_max in YYYY-MM-DD format."
          },
          "apiPageSize": {
            "title": "API page size",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many ads to request per Meta API page. Meta currently caps this conservatively, so 100 is the default.",
            "default": 100
          },
          "maxApiPages": {
            "title": "Max API pages",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Safety cap for API pagination. Lower values reduce cost when filters are too strict.",
            "default": 25
          },
          "searchType": {
            "title": "Search type",
            "enum": [
              "KEYWORD_UNORDERED",
              "KEYWORD_EXACT_PHRASE"
            ],
            "type": "string",
            "description": "KEYWORD_UNORDERED returns more results. KEYWORD_EXACT_PHRASE is stricter and may return very few ads.",
            "default": "KEYWORD_UNORDERED"
          },
          "ctaFilter": {
            "title": "Call to action filter",
            "type": "string",
            "description": "CTA values such as SHOP NOW, ORDER NOW, or LEARN MORE. Separate multiple CTAs with commas or AND. With Require CTA match enabled, rows are kept when the returned CTA field or exact creative text fallback matches."
          },
          "language": {
            "title": "Language filter",
            "type": "string",
            "description": "Optional ad language code. Use ar for Arabic, en for English, fr for French. Leave empty to keep all languages."
          },
          "mediaType": {
            "title": "Media type filter",
            "enum": [
              "ALL",
              "IMAGE",
              "VIDEO",
              "MEME",
              "NONE"
            ],
            "type": "string",
            "description": "Optional Meta API media_type search filter. Use ALL, IMAGE, VIDEO, MEME, or NONE. This is sent to Meta before pagination to reduce API pages and compute.",
            "default": "ALL"
          },
          "languages": {
            "title": "Language filters advanced",
            "type": "array",
            "description": "Optional ISO 639 language codes for Meta's languages API parameter. Example: [\"ar\"] for Arabic or [\"ar\", \"fr\"] for both.",
            "default": []
          },
          "requireCtaMatch": {
            "title": "Require CTA match",
            "type": "boolean",
            "description": "When enabled, discard ads before saving if returned API CTA fields match the selected CTA filter. Keep disabled when using snapshot CTA enrichment or n8n CTA status columns.",
            "default": false
          },
          "maxStrictCtaNoMatchPages": {
            "title": "Max CTA no-match pages",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "When strict CTA matching is enabled, stop early after this many consecutive API pages have no matching CTA.",
            "default": 3
          },
          "metaAccessToken": {
            "title": "Meta access token",
            "type": "string",
            "description": "Optional temporary Meta Graph API token. If empty, the actor uses the META_TOKEN secret from Actor settings. Paste a real token only; do not copy ENCRYPTED_VALUE placeholders from old Apify run inputs."
          },
          "enableSnapshotEnrichment": {
            "title": "Enrich snapshot pages",
            "type": "boolean",
            "description": "Open each saved ad snapshot page with Playwright to extract cleaner headline, CTA, media type, carousel count, and destination URL. Leave off for the lowest cost.",
            "default": false
          },
          "snapshotConcurrency": {
            "title": "Snapshot concurrency",
            "minimum": 1,
            "maximum": 3,
            "type": "integer",
            "description": "Maximum snapshot pages opened at the same time. Capped at 3 to control compute and bandwidth.",
            "default": 3
          },
          "snapshotBatchSize": {
            "title": "Snapshot save batch size",
            "minimum": 1,
            "maximum": 25,
            "type": "integer",
            "description": "How many snapshot-enriched ads to process before saving to the dataset. Smaller batches prevent empty datasets if long snapshot runs time out.",
            "default": 10
          },
          "maxSnapshotEnrichments": {
            "title": "Max enriched snapshots",
            "minimum": 0,
            "maximum": 5000,
            "type": "integer",
            "description": "Maximum number of saved ads to enrich with snapshot page parsing. Lower this when testing to avoid extra compute.",
            "default": 100
          },
          "snapshotTimeLimitSecs": {
            "title": "Snapshot time limit seconds",
            "minimum": 0,
            "maximum": 3600,
            "type": "integer",
            "description": "Maximum time spent opening snapshot pages for CTA and landing-page extraction. When reached, remaining API results are still saved without snapshot enrichment so the Actor does not time out.",
            "default": 480
          },
          "anthropicApiKey": {
            "title": "Anthropic API key for Vision fallback",
            "type": "string",
            "description": "Optional. Used only when semantic selectors and text scan cannot find CTA text. Leave empty to avoid Vision LLM cost."
          },
          "relaxSearchOnNoResults": {
            "title": "Relax search when exact keyword has no results",
            "type": "boolean",
            "description": "When enabled, a multi-word keyword such as 'pillow sleep' is retried with the first word if the exact active search returns 0 ads. Useful for n8n sheets so strict phrases do not produce empty datasets.",
            "default": true
          },
          "failOnNoResults": {
            "title": "Fail when no ads are found",
            "type": "boolean",
            "description": "When enabled, the Actor fails instead of silently succeeding with an empty dataset. Recommended for n8n so token/API/filter problems are visible.",
            "default": true
          },
          "forceMode": {
            "title": "Scraping mode",
            "enum": [
              "auto",
              "api",
              "browser"
            ],
            "type": "string",
            "description": "api = lowest cost and no proxy. auto = API first, then DATACENTER browser fallback. browser = browser only for debugging.",
            "default": "api"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}