{
  "openapi": "3.0.1",
  "info": {
    "title": "Snapchat Ads Scraper",
    "description": "Scrape Snapchat ads from the official Ads Gallery API + Political Ads Library — creatives, impressions, targeting, and spend.",
    "version": "0.1",
    "x-build-id": "7vQUslb6s3etOfKeE"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~snapchat-ads-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-snapchat-ads-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/khadinakbar~snapchat-ads-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-snapchat-ads-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/khadinakbar~snapchat-ads-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-snapchat-ads-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": {
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "creator",
              "political"
            ],
            "type": "string",
            "description": "Which Snapchat data source to scrape. 'search' queries the official EU Ads Gallery for a brand's commercial ads; 'creator' pulls sponsored/branded content by a creator name; 'political' downloads the worldwide Political Ads Library archive with spend and targeting. Defaults to 'search'. This is NOT a Snapchat profile, Story, or Spotlight scraper.",
            "default": "search"
          },
          "advertiserName": {
            "title": "Advertiser / brand name",
            "type": "string",
            "description": "Paying advertiser to search in the Ads Gallery (e.g. 'Nike'). Required in 'search' mode; matches Snapchat's paying advertiser name. The Ads Gallery cannot list all advertisers at once, so a brand name is needed. NOT a Snapchat username — for creators use creatorName."
          },
          "countries": {
            "title": "Countries (Ads Gallery)",
            "type": "array",
            "description": "EU/EEA countries (2-letter ISO codes) to include in 'search' mode. The Ads Gallery only covers ads delivered in these markets in the last 12 months. Defaults to all 27 supported countries when left empty. Codes outside this list are rejected by Snapchat.",
            "items": {
              "type": "string",
              "enum": [
                "at",
                "be",
                "bg",
                "hr",
                "cy",
                "cz",
                "dk",
                "ee",
                "fi",
                "fr",
                "de",
                "el",
                "hu",
                "ie",
                "it",
                "lv",
                "lt",
                "lu",
                "mt",
                "nl",
                "pl",
                "pt",
                "ro",
                "sk",
                "si",
                "es",
                "se"
              ]
            },
            "default": []
          },
          "status": {
            "title": "Ad status (Ads Gallery)",
            "enum": [
              "ANY",
              "ACTIVE",
              "PAUSED"
            ],
            "type": "string",
            "description": "Filter Ads Gallery results by delivery status. 'ANY' returns both active and paused ads; 'ACTIVE' only currently delivering ads; 'PAUSED' only stopped ads. Defaults to 'ANY'. Applies only to 'search' mode.",
            "default": "ANY"
          },
          "startDate": {
            "title": "Start date (Ads Gallery)",
            "type": "string",
            "description": "Only return Ads Gallery ads delivered on or after this date. Use ISO-8601 format (e.g. '2025-01-01'). Leave empty for no lower bound. Applies only to 'search' mode."
          },
          "endDate": {
            "title": "End date (Ads Gallery)",
            "type": "string",
            "description": "Only return Ads Gallery ads delivered on or before this date. Use ISO-8601 format (e.g. '2025-12-31'). Leave empty for no upper bound. Applies only to 'search' mode."
          },
          "creatorName": {
            "title": "Creator name (Creator mode)",
            "type": "string",
            "description": "Creator / public profile name for 'creator' mode (e.g. 'kyliejenner'). Returns sponsored and branded content associated with that creator. Required when mode = 'creator'; ignored otherwise. NOT a brand — for brands use advertiserName."
          },
          "politicalYears": {
            "title": "Years (Political mode)",
            "type": "array",
            "description": "Years of the Political Ads Library archive to download in 'political' mode. Each year is a separate official Snap CSV archive of political/advocacy ads worldwide. Defaults to ['2025']. Add multiple years to combine, e.g. ['2024','2025'].",
            "items": {
              "type": "string",
              "enum": [
                "2018",
                "2019",
                "2020",
                "2021",
                "2022",
                "2023",
                "2024",
                "2025",
                "2026"
              ]
            },
            "default": [
              "2025"
            ]
          },
          "politicalCountry": {
            "title": "Country filter (Political mode)",
            "type": "string",
            "description": "Optional 2-letter country filter for 'political' mode (e.g. 'us'). Keeps only rows whose CountryCode matches. Leave empty for all countries. Case-insensitive."
          },
          "politicalSearchTerm": {
            "title": "Keyword filter (Political mode)",
            "type": "string",
            "description": "Optional free-text filter for 'political' mode; keeps only rows containing this term (advertiser, organization, candidate, etc.). Case-insensitive substring match across all columns. Leave empty for no filter."
          },
          "maxResults": {
            "title": "Max results",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Maximum number of records to return and bill for across all pages and years. Hard cap is 50000. Defaults to 100. Billing stops once this number is reached.",
            "default": 100
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Defaults to Apify Proxy. Both data sources are public with no anti-bot, so datacenter proxy is sufficient; proxy mainly spreads request volume. Leave at default unless you have a reason to change it.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}