{ "openapi": "3.0.1", "info": { "title": "LinkedIn Ad Library Scraper - Impressions, Targeting & Dates", "description": "Scrape the LinkedIn Ad Library by keyword, advertiser, payer, country and date: ad copy, format, media, landing URL, CTA, paid-for-by, run dates, total impressions, impressions by country and targeting. Monitor new ads. No login, no cookies.", "version": "0.1", "x-build-id": "TEJPkK8cix8c2ZsPd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/topapi~linkedin-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-topapi-linkedin-ad-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/topapi~linkedin-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-topapi-linkedin-ad-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/topapi~linkedin-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-topapi-linkedin-ad-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": "๐Ÿ”ค Keywords", "type": "array", "description": "Words in the ad copy, as typed into the Ad Library's keyword box, e.g. \"salesforce\", \"AI agents\", \"cybersecurity\".", "items": { "type": "string" } }, "advertisers": { "title": "๐Ÿข Advertisers", "type": "array", "description": "Company or advertiser names, slugs or company URLs, e.g. \"HubSpot\", \"the-home-depot\", \"https://www.linkedin.com/company/nvidia/\". LinkedIn matches names that contain the text; see Advertiser match.", "items": { "type": "string" } }, "payers": { "title": "๐Ÿ’ณ Payers", "type": "array", "description": "The \"Paid for by\" entity, e.g. \"HubSpot, Inc.\". Finds ads an agency or parent company paid for.", "items": { "type": "string" } }, "startUrls": { "title": "๐Ÿ”— Ad Library URLs", "type": "array", "description": "Paste Ad Library search URLs (every filter in the URL is kept), ad URLs (/ad-library/detail/) or company URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "adIds": { "title": "๐Ÿ†” Ad ids", "type": "array", "description": "Ad Library ad ids, e.g. \"1633495836\". Each one is read from its detail page.", "items": { "type": "string" } }, "searches": { "title": "๐Ÿงฉ Searches (advanced)", "type": "array", "description": "Independent searches, each with its own filters: [{\"keyword\":\"crm\",\"countries\":[\"DE\"],\"dateOption\":\"last-30-days\"},{\"advertiser\":\"HubSpot\",\"maxResults\":50}]. Keys: keyword, advertiser, payer, countries, dateOption, startDate, endDate, impressions*, includedTargetingFacetCategories, excludedTargetingFacetCategories, sortBy, maxResults." }, "countries": { "title": "๐ŸŒ Countries", "type": "array", "description": "Countries where the ad was shown. Ads shown in the EU carry impressions and targeting on their detail page.", "items": { "type": "string", "enumSuggestedValues": [ "US", "GB", "DE", "FR", "CA", "AU", "IN", "NL", "ES", "IT", "IE", "SE", "CH", "BE", "AT", "DK", "NO", "FI", "PL", "BR", "MX", "SG", "AE", "JP", "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AZ", "BS", "BH", "BD", "BB", "BY", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CV", "CB", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CK", "CR", "CI", "HR", "CU", "CY", "CZ", "CD", "DJ", "DM", "DO", "TP", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FM", "FJ", "GF", "PF", "TF", "GA", "GM", "GE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "ID", "IR", "IQ", "IM", "IL", "JM", "JE", "JO", "KZ", "KE", "KI", "KR", "KP", "KO", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "AN", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "GS", "SH", "KN", "LC", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "CS", "SC", "SL", "SK", "SI", "SB", "SO", "ZA", "SS", "LK", "SD", "OM", "SR", "SJ", "SZ", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "UY", "UZ", "VU", "VA", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "YU", "ZM", "ZW" ], "enumTitles": [ "United States", "United Kingdom", "Germany", "France", "Canada", "Australia", "India", "Netherlands", "Spain", "Italy", "Ireland", "Sweden", "Switzerland", "Belgium", "Austria", "Denmark", "Norway", "Finland", "Poland", "Brazil", "Mexico", "Singapore", "United Arab Emirates", "Japan", "Afghanistan", "Aland Islands", "Albania", "Algeria", "American Samoa", "Andorra", "Angola", "Anguilla", "Antarctica", "Antigua and Barbuda", "Argentina", "Armenia", "Aruba", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", "Bosnia and Herzegovina", "Botswana", "Bouvet Island", "British Indian Ocean Territory", "Brunei Darussalam", "Bulgaria", "Burkina Faso", "Burundi", "Cambodia", "Cameroon", "Cape Verde", "Caribbean Nations", "Cayman Islands", "Central African Republic", "Chad", "Chile", "China", "Christmas Island", "Cocos (Keeling) Islands", "Colombia", "Comoros", "Congo", "Cook Islands", "Costa Rica", "Cote Dโ€™Ivoire (Ivory Coast)", "Croatia", "Cuba", "Cyprus", "Czech Republic", "Democratic Republic of the Congo", "Djibouti", "Dominica", "Dominican Republic", "East Timor", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", "Estonia", "Ethiopia", "Falkland Islands (Malvinas)", "Faroe Islands", "Federated States of Micronesia", "Fiji", "French Guiana", "French Polynesia", "French Southern Territories", "Gabon", "Gambia", "Georgia", "Ghana", "Gibraltar", "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guernsey", "Guinea", "Guinea-Bissau", "Guyana", "Haiti", "Heard Island and McDonald Islands", "Honduras", "Hong Kong", "Hungary", "Iceland", "Indonesia", "Iran", "Iraq", "Isle of Man", "Israel", "Jamaica", "Jersey", "Jordan", "Kazakhstan", "Kenya", "Kiribati", "Korea", "Korea (North)", "Kosovo", "Kuwait", "Kyrgyzstan", "Laos", "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", "Macao", "Macedonia", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", "Martinique", "Mauritania", "Mauritius", "Mayotte", "Moldova", "Monaco", "Mongolia", "Montenegro", "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", "Nauru", "Nepal", "Netherlands Antilles", "New Caledonia", "New Zealand", "Nicaragua", "Niger", "Nigeria", "Niue", "Norfolk Island", "Northern Mariana Islands", "Pakistan", "Palau", "Palestinian Territory", "Panama", "Papua New Guinea", "Paraguay", "Peru", "Philippines", "Pitcairn", "Portugal", "Puerto Rico", "Qatar", "Reunion", "Romania", "Russian Federation", "Rwanda", "S. Georgia and S. Sandwich Islands", "Saint Helena", "Saint Kitts and Nevis", "Saint Lucia", "Saint Pierre and Miquelon", "Saint Vincent and the Grenadines", "Samoa", "San Marino", "Sao Tome and Principe", "Saudi Arabia", "Senegal", "Serbia", "Serbia and Montenegro", "Seychelles", "Sierra Leone", "Slovak Republic", "Slovenia", "Solomon Islands", "Somalia", "South Africa", "South Sudan", "Sri Lanka", "Sudan", "Sultanate of Oman", "Suriname", "Svalbard and Jan Mayen", "Swaziland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "Timor-Leste", "Togo", "Tokelau", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkey", "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Uganda", "Ukraine", "Uruguay", "Uzbekistan", "Vanuatu", "Vatican City State (Holy See)", "Venezuela", "Vietnam", "Virgin Islands (British)", "Virgin Islands (U.S.)", "Wallis and Futuna", "Western Sahara", "Yemen", "Yugoslavia", "Zambia", "Zimbabwe" ] } }, "dateOption": { "title": "๐Ÿ“… Date range", "enum": [ "all-time", "last-30-days", "current-month", "current-year", "last-year", "custom-date-range" ], "type": "string", "description": "When the ad ran. \"Custom\" uses Start and End date below. LinkedIn keeps about a year of history.", "default": "all-time" }, "startDate": { "title": "Start date", "type": "string", "description": "Custom range start (YYYY-MM-DD or relative, e.g. \"30 days\"). Setting a date switches to a custom range." }, "endDate": { "title": "End date", "type": "string", "description": "Custom range end (YYYY-MM-DD). Empty = today." }, "impressionsMinValue": { "title": "๐Ÿ‘๏ธ Impressions at least", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Lower bound of LinkedIn's impressions filter, with the unit below, e.g. 100 + Thousand." }, "impressionsMinUnit": { "title": "Unit (at least)", "enum": [ "none", "thousand", "million" ], "type": "string", "description": "Unit of the lower bound.", "default": "thousand" }, "impressionsMaxValue": { "title": "๐Ÿ‘๏ธ Impressions at most", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Upper bound, e.g. 10 + Million. LinkedIn needs both bounds; a missing one is filled in." }, "impressionsMaxUnit": { "title": "Unit (at most)", "enum": [ "none", "thousand", "million" ], "type": "string", "description": "Unit of the upper bound.", "default": "thousand" }, "includedTargetingFacetCategories": { "title": "๐ŸŽฏ Targeting uses", "type": "array", "description": "Only ads whose targeting includes these categories, e.g. Job (titles, functions, seniority).", "items": { "type": "string", "enumSuggestedValues": [ "LANGUAGE", "LOCATION", "AUDIENCE", "DEMOGRAPHIC", "COMPANY", "EDUCATION", "JOB", "INTERESTS_AND_TRAITS" ], "enumTitles": [ "Language", "Location", "Audience", "Demographic", "Company", "Education", "Job", "Member interests and traits" ] } }, "excludedTargetingFacetCategories": { "title": "๐Ÿšซ Targeting excludes", "type": "array", "description": "Only ads whose targeting excludes these categories.", "items": { "type": "string", "enumSuggestedValues": [ "LANGUAGE", "LOCATION", "AUDIENCE", "DEMOGRAPHIC", "COMPANY", "EDUCATION", "JOB", "INTERESTS_AND_TRAITS" ], "enumTitles": [ "Language", "Location", "Audience", "Demographic", "Company", "Education", "Job", "Member interests and traits" ] } }, "sortBy": { "title": "โ†•๏ธ Sort", "enum": [ "newest", "oldest" ], "type": "string", "description": "LinkedIn's two sort orders.", "default": "newest" }, "advertiserMatch": { "title": "๐Ÿข Advertiser match", "enum": [ "contains", "exact" ], "type": "string", "description": "For advertiser searches. LinkedIn returns every advertiser whose name contains the text (\"HubSpot\" also finds \"HubSpot Platinum Partner\"); Exact keeps the company itself.", "default": "contains" }, "adFormats": { "title": "๐Ÿ–ผ๏ธ Ad formats", "type": "array", "description": "Keep only these formats. Empty = all.", "items": { "type": "string", "enumSuggestedValues": [ "SINGLE_IMAGE", "VIDEO", "CAROUSEL", "DOCUMENT", "EVENT", "MESSAGE", "TEXT", "ARTICLE", "JOB", "FOLLOW_COMPANY", "SPOTLIGHT", "TEXT_ONLY", "THOUGHT_LEADER" ], "enumTitles": [ "Single image", "Video", "Carousel", "Document", "Event", "Message / InMail / Conversation", "Text ad (right rail)", "Article / newsletter", "Job ad", "Follow company", "Spotlight", "Text-only post", "Thought leader (member post)" ] } }, "includeEmployerBranding": { "title": "๐Ÿ’ผ Include job and follow-company ads", "type": "boolean", "description": "Off = drop employer-brand promos (job ads, follow-company ads) from the results.", "default": true }, "excludeKeywords": { "title": "๐Ÿšซ Exclude keywords", "type": "array", "description": "Drop ads whose advertiser, headline or copy contains any of these words (case-insensitive), e.g. \"webinar\".", "items": { "type": "string" } }, "onlyWithImpressions": { "title": "๐Ÿ“Š Only ads with impressions data", "type": "boolean", "description": "Keep only ads whose detail page shows impressions (ads shown in the EU). Needs Ad details on.", "default": false }, "onlyActive": { "title": "๐ŸŸข Only running ads", "type": "boolean", "description": "Keep only ads whose run dates reach today or yesterday. Run dates exist for ads shown in the EU; needs Ad details on.", "default": false }, "minDaysRunning": { "title": "โณ Min days running", "minimum": 0, "maximum": 3650, "type": "integer", "description": "Keep only ads that ran at least this many days (from the run dates on the detail page), e.g. 30 for proven creatives." }, "scrapeAdDetails": { "title": "๐Ÿ“„ Ad details", "type": "boolean", "description": "Open each ad's detail page: full copy, CTA labels, paid-for-by, variants and, for ads shown in the EU, the CTA landing URL, run dates, impressions, impressions by country and targeting. On other ads the landing URL comes from links in the ad copy, with short links followed (landingUrlSource \"adCopy\"). Charged as \"ad-details\" per ad.", "default": true }, "monitorMode": { "title": "๐Ÿ” Only new ads", "type": "boolean", "description": "Return only ads not delivered by earlier runs that used the same monitor store. Ads already known are skipped and not charged.", "default": false }, "monitorChanges": { "title": "๐Ÿ“ˆ Also report changed ads", "type": "boolean", "description": "With monitoring and Ad details on: also deliver known ads whose impressions range or end date changed (with the previous values). Each poll re-checks the known ads on the pages it reads (the newest 24 per search once nothing new appears); unchanged ads are not charged.", "default": false }, "monitorStoreName": { "title": "๐Ÿ—„๏ธ Monitor store name", "type": "string", "description": "Named key-value store that remembers delivered ads. Use one name per tracked set, e.g. \"competitor-ads\".", "default": "linkedin-ad-library-monitor" }, "maxResults": { "title": "๐Ÿ”ข Max ads", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Most ads for the whole run. 0 = no limit (a broad keyword can match 200,000+ ads).", "default": 100 }, "maxResultsPerSearch": { "title": "๐Ÿ”ข Max ads per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Ceiling for each keyword, advertiser, payer or URL, so one large search does not use the whole run. 0 = no per-search limit." }, "countOnly": { "title": "๐Ÿงฎ Count only", "type": "boolean", "description": "Return one free row per search with LinkedIn's total ad count, without the ads. Ad ids and ad URLs are skipped in this mode (not delivered, not charged).", "default": false }, "compact": { "title": "๐Ÿ—œ๏ธ Compact output", "type": "boolean", "description": "Core fields only, sized for AI agents and MCP clients.", "default": false }, "proxyConfiguration": { "title": "๐Ÿ›ก๏ธ Proxy", "type": "object", "description": "Apify Proxy (default, datacenter). Each parallel request stream uses its own proxy session.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "โšก Parallel sessions", "minimum": 1, "maximum": 8, "type": "integer", "description": "Proxy sessions working in parallel. LinkedIn allows about one request every 2 seconds per IP, so more sessions = faster.", "default": 4 }, "requestDelayMs": { "title": "โฑ๏ธ Delay per session (ms)", "minimum": 1500, "maximum": 20000, "type": "integer", "description": "Pause between two requests on the same session.", "default": 2200 } } }, "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 } } } } } } } } } }