{ "openapi": "3.0.1", "info": { "title": "Snapchat Political Ads Scraper: Spend & Targeting", "description": "Scrape Snap's Political Ads Library, 80,000+ ads from 54 countries since 2018, no login or API key. Get the paying advertiser, organization, candidate or ballot, spend, impressions, dates, targeted regions, ages, interests and a direct media link. JSON, CSV or API; pay per ad delivered.", "version": "0.1", "x-build-id": "RVAK4zqco85ShYU9K" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation_craft~snapchat-political-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation_craft-snapchat-political-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/automation_craft~snapchat-political-ads-scraper/runs": { "post": { "operationId": "runs-sync-automation_craft-snapchat-political-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/automation_craft~snapchat-political-ads-scraper/run-sync": { "post": { "operationId": "run-sync-automation_craft-snapchat-political-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": { "years": { "title": "Years", "type": "array", "description": "The yearly files to read. Pick one or several, or All years for the whole archive since 2018. An ad sits in the file of the year Snap assigned it to, which is the year it started in for 99 percent of ads. Leave empty for the newest yearly file. Through the API pass years as text, for example [\"2026\", \"2024\"], or [\"all\"].", "items": { "type": "string", "enum": [ "all", "2026", "2025", "2024", "2023", "2022", "2021", "2020", "2019", "2018" ], "enumTitles": [ "All years (2018 to today)", "2026", "2025", "2024", "2023", "2022", "2021", "2020", "2019", "2018" ] } }, "countries": { "title": "Countries", "type": "array", "description": "Keep only ads delivered in these countries. Use ISO two letter codes such as US, GB, FR, NO, or English country names such as United States. Leave empty for every country. The archive holds ads from 54 countries; about 73 percent are United States ads.", "items": { "type": "string" } }, "search": { "title": "Advertiser, organization or candidate", "type": "array", "description": "Names or keywords, one per line, for example Planned Parenthood, or Proposition 50. An ad matches when every word of a term appears as a whole word in ONE of these fields: paying advertiser, organization, candidate or ballot information, committee name, disclosure name of the committee. Capitals, accents and punctuation make no difference. Several terms: an ad that matches any of them is delivered once, and the row says which terms and fields matched. A term nobody matches costs nothing; the run summary counts the matches per term. Up to 200 terms.", "items": { "type": "string" } }, "searchMatch": { "title": "How a search term matches", "enum": [ "words", "exact" ], "type": "string", "description": "words: every word of the term appears in the field as a whole word, in any order (Biden finds Biden for President). exact: the field is exactly the term, word for word.", "default": "words" }, "startedWithinDays": { "title": "Started in the last N days", "minimum": 1, "maximum": 3650, "type": "integer", "description": "Keep only ads whose start date is within this many days before the run started, up to the moment it started, for example 7. Cannot be combined with the two date fields below. Note that Snap adds some ads to the file days or months after their start date; to catch every new ad on a schedule use a monitor name instead." }, "startedFrom": { "title": "Started from", "type": "string", "description": "Keep only ads whose start date is on or after this day, YYYY-MM-DD, for example 2026-01-01." }, "startedTo": { "title": "Started to", "type": "string", "description": "Keep only ads whose start date is on or before this day, YYYY-MM-DD." }, "status": { "title": "Status", "enum": [ "all", "active", "ended" ], "type": "string", "description": "all: every ad. active: ads that have started and have no end date in the past, judged at the moment the run starts. ended: ads whose end date has passed.", "default": "all" }, "minSpend": { "title": "Minimum spend", "minimum": 0, "type": "integer", "description": "Keep only ads that spent at least this amount, in the ad's own currency, whole units, for example 1000. Snap reports spend per ad as the total up to the day the file was written." }, "minImpressions": { "title": "Minimum impressions", "minimum": 0, "type": "integer", "description": "Keep only ads with at least this many impressions, for example 100000." }, "currencies": { "title": "Currencies", "type": "array", "description": "Keep only ads billed in these currencies, as three letter codes: USD, EUR, GBP, NOK, CAD, AUD, SEK, INR, DKK, NZD, AED. Leave empty for every currency.", "items": { "type": "string" } }, "targetRegions": { "title": "Targeted regions", "type": "array", "description": "Keep only ads whose included regions, metros or electoral districts name one of these, exactly as Snap writes them, one per line: for example Pennsylvania, Arizona, Las Vegas, California 45th District. Capitals make no difference. An ad that targets a whole country without naming regions does not match.", "items": { "type": "string" } }, "sortBy": { "title": "Order", "enum": [ "newest", "spend", "impressions" ], "type": "string", "description": "The order of the rows, which also decides which ads are delivered when more match than the row cap allows. newest: latest start date first. spend: highest spend first (amounts in different currencies are compared as plain numbers). impressions: most impressions first.", "default": "newest" }, "maxItems": { "title": "Maximum ads", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "The most Political ad rows this run may deliver (and charge). A free row says how many more matched. When the field is left out, 100 is used. For a whole yearly file set it above the file's size, for example 100000." }, "monitorName": { "title": "Monitor name (deliver only new ads)", "type": "string", "description": "Give a name, for example us-midterms-2026, and schedule the run: each ad is delivered and charged once per monitor name, later runs skip what the monitor already delivered, including ads Snap adds to the file late. Use a new name when you change the filters. Two runs on one name at the same time: the second delivers nothing. Leave empty for a plain run." }, "includeSourceColumns": { "title": "Add Snap's 38 columns as written", "type": "boolean", "description": "Adds an object sourceColumns to every row with the 38 columns of Snap's file exactly as the file has them (column names and text unchanged), next to the parsed fields. For researchers who want to reproduce the original CSV. No extra charge.", "default": false } } }, "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 } } } } } } } } } }