# LinkedIn Ad Library Search Scraper (`khadinakbar/linkedin-ad-library-search-scraper`) Actor Search public LinkedIn Ad Library ads by advertiser or keyword, with normalized creatives and EU transparency fields. - **URL**: https://apify.com/khadinakbar/linkedin-ad-library-search-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, Automation, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $6.00 / 1,000 ad records This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## LinkedIn Ad Library Search Scraper Search public LinkedIn Ad Library records by advertiser or creative keyword. This Actor returns normalized ad creatives, advertiser information, call-to-action links, and public EU transparency data when LinkedIn makes it available. It is designed for B2B competitive-intelligence teams, creative analysts, and AI agents that need a bounded JSON record rather than a browser export. ### When to use this Actor Use this Actor to research an advertiser's visible LinkedIn creative, discover ads that mention a product category, review campaign timing, or compare eligible EU transparency signals. Start with one advertiser or one keyword and a small result cap, then paginate only when the first result set is relevant. The default uses `Microsoft` so a new run is valid, fast, and easy to inspect. You do not need to supply LinkedIn cookies, a browser session, or a Campaign Manager account. Do not use it for LinkedIn profiles, private Campaign Manager reporting, member data, lead lists, or exact ad-performance analytics. The output only reflects public Ad Library information made available by the underlying provider routes. LinkedIn documents that its Ad Library may be searched by company/advertiser, payer, keyword, country, and date range; LinkedIn also notes that ads remain in the library for one year after their last impression. [LinkedIn Ad Library Help](https://www.linkedin.com/help/linkedin/answer/a1517918) ### What you receive Each dataset item is one normalized public ad. Keys are stable across search-only and detail-enriched runs; unavailable fields are `null` or empty arrays, never omitted. | Field | Meaning | | --- | --- | | `adId`, `adUrl` | Public LinkedIn Ad Library identifier and detail page URL. | | `advertiserName`, `advertiserLinkedInUrl` | Disclosed advertiser identity and public LinkedIn company URL when returned. | | `headline`, `description`, `adType`, `cta` | The public creative text and format. | | `destinationUrl`, `imageUrl`, `videoUrl` | Public creative and landing-page URLs when returned. | | `adRunStart`, `adRunEnd`, `estimatedImpressions` | Transparency fields that LinkedIn may show for eligible ads. Impression ranges are not exact counts. | | `impressionCountries`, `targetingSummary` | Bounded country-share and targeting arrays in `detailed` mode. These are not a complete audience definition. | | `searchType`, `searchTerm`, `searchCountries` | Provenance showing how this record was found. | | `sourceProvider`, `detailProvider`, `detailsFetched` | The provider route used and whether optional detail enrichment succeeded. | For ads targeted in the European Union, LinkedIn says the Ad Library can show estimated impressions, country-level impression breakdowns, targeting parameters, and dates the ad ran. Those fields are therefore descriptive transparency signals, not an exhaustive view of an advertiser's targeting. [LinkedIn transparency help](https://www.linkedin.com/help/linkedin/answer/a1631257) ### Inputs Use `advertisers` for a known company, for example `Microsoft` or `HubSpot`. Use `keywords` for creative-level research, for example `CRM software`. Supplying both creates independent advertiser and keyword searches so provenance remains clear. `countries` accepts ISO alpha-2 codes such as `US`, `DE`, and `GB`; leave it empty to avoid a country filter. `maxResults` is the hard cap on persisted, primary-event-billed records. `maxPagesPerSearch` bounds provider pagination independently so you can control breadth before increasing the record cap. Optional `startDate` and `endDate` must use `YYYY-MM-DD` and may be used independently. Invalid dates, inverted ranges, invalid country codes, and unsupported enum values return an actionable `INVALID_INPUT` outcome without billing result events. Set `fetchAdDetails` to `true` when you need a second provider call per saved record. Detail enrichment can provide fuller public creative, date, impression, country-share, and targeting values. Set it to `false` for faster creative discovery when the search response is enough. `responseFormat: concise` keeps array fields empty for smaller agent payloads; `detailed` includes bounded media, country, and targeting arrays. ### Input examples #### Console input ```json { "advertisers": ["Microsoft"], "countries": ["US", "DE"], "maxResults": 20, "maxPagesPerSearch": 1, "fetchAdDetails": true, "providerPreference": "scrapecreators-first", "responseFormat": "detailed" } ```` #### JavaScript API ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('khadinakbar/linkedin-ad-library-search-scraper').call({ keywords: ['CRM software'], countries: ['US'], maxResults: 10, fetchAdDetails: false, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` #### Python API ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('khadinakbar/linkedin-ad-library-search-scraper').call(run_input={ 'advertisers': ['HubSpot'], 'maxResults': 10, 'fetchAdDetails': True, 'responseFormat': 'concise', }) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item['advertiserName'], item['adUrl']) ``` ### Pricing This Actor uses Pay per event + platform usage. Platform usage is billed separately by Apify; the result limit and the status message show the maximum event-charge envelope before collection begins. | Event | Price | Charged when | | --- | ---: | --- | | Actor start | $0.00005 | Once per run, scaled by Actor memory. | | Ad record | $0.006 | A complete normalized public ad record is persisted to the dataset. | | Ad detail enrichment | $0.004 | Optional detail enrichment succeeds after that record has been saved. | For example, a maximum of 10 detailed records has at most $0.10 in event charges ($0.06 record events + $0.04 detail events), plus platform usage. A search-only run at the same cap has at most $0.06 in record events, plus platform usage. The Actor never charges an ad-record event before its validated dataset row is written, and it never charges a detail event after a failed detail request. ### Reliability and output outcomes ScrapeCreators is the default provider route and SociaVault is the fallback. Both routes were probed for search and ad-detail field parity before this Actor was built. The Actor reports the attempted provider routes in `RUN_SUMMARY` without exposing provider credentials. It never accepts a user-supplied provider API key. Every terminal path writes two key-value store records: - `OUTPUT` is the compact contract with `outcome`, persisted counts, event counts, and safe warnings. - `RUN_SUMMARY` contains provider attempts, pages fetched, write failures, billing counters, and timestamps. `COMPLETE` means all persisted records were collected without route or write warnings. `PARTIAL` means usable records were persisted but a search, detail, validation, or cost-cap condition prevented full completion. `VALID_EMPTY` means a valid provider search returned no matching ads. `INVALID_INPUT` means the request can be corrected by changing the supplied inputs. `UPSTREAM_FAILED` means every configured provider route failed or returned unusable data before any record could be saved. These outcome records let an agent distinguish no matches from an outage without parsing logs. ### Limits and compliance The Actor only returns public Ad Library data exposed by its configured providers. Restricted ads can have redacted previews or advertiser and payer fields, as LinkedIn describes in its Ad Library documentation. Data availability, field depth, and result counts can vary by country, date, and the underlying public record. Keep result caps small when exploring a new query, validate data against your own use case, and respect applicable laws, contractual obligations, and privacy requirements. ### Related workflow Use this Actor for public ad intelligence. Route LinkedIn profile or company enrichment to a dedicated profile/company Actor, and use a CRM or analytics system for private campaign performance. For long-running monitoring, save the exact input that produced useful results and compare future outputs by `adId` and `adUrl` rather than assuming a complete archive. # Actor input Schema ## `advertisers` (type: `array`): Use this when you know the company or advertiser whose public ads you want to review. Enter a list of display names such as Microsoft or HubSpot. Defaults to Microsoft only when neither advertisers nor keywords is supplied. This is not a LinkedIn company URL or a private Campaign Manager account ID. ## `keywords` (type: `array`): Use this when you want public ads whose creative matches a phrase instead of one known advertiser. Enter plain keywords such as CRM software or data warehouse. Defaults to no keyword searches, and each keyword becomes an independent search. This is not a Boolean LinkedIn profile query or a list of campaign IDs. ## `countries` (type: `array`): Use this when results should be limited to countries reported by the Ad Library. Enter ISO alpha-2 codes such as US, DE, or GB. Defaults to no country filter, while supplied codes are sent together to each search. This is not a proxy location setting or a city-level targeting filter. ## `startDate` (type: `string`): Use this when limiting ads by the beginning of their reported run window. Enter an ISO date such as 2026-01-01. Defaults to no lower date boundary and may be used with or without an end date. This is not a timestamp, a relative date phrase, or a campaign launch prediction. ## `endDate` (type: `string`): Use this when limiting ads by the end of their reported run window. Enter an ISO date such as 2026-06-30. Defaults to no upper date boundary and must not be before startDate when both are supplied. This is not an expiry estimate or a relative date phrase. ## `maxResults` (type: `integer`): Use this to cap the number of normalized ad records saved and billed in this run. Enter an integer such as 20 between 1 and 100. Defaults to 20, which also caps the primary event charge before platform usage. This is not a page number or a guarantee that the Ad Library contains that many matches. ## `maxPagesPerSearch` (type: `integer`): Use this to bound provider pagination for every advertiser or keyword search. Enter an integer such as 2 between 1 and 10. Defaults to 1 page so the actor remains fast and cost-predictable. This is not an overall record limit because maxResults controls persisted ads. ## `fetchAdDetails` (type: `boolean`): Use this when you need a second verified provider call per saved ad for richer public transparency data. Set true to request details and false to use the normalized search response only. Defaults to true and adds the documented detail-enrichment event only after a successful detail fetch. This is not a request for private advertiser, member, or Campaign Manager data. ## `providerPreference` (type: `string`): Use this to choose which configured public-data provider is attempted first. Select scrapecreators-first or sociavault-first. Defaults to scrapecreators-first, and the other configured provider is tried after a route failure. This is not a user API key field or a promise that one provider has private LinkedIn data. ## `responseFormat` (type: `string`): Use this to choose the token budget of each saved ad record. Select concise for core creative and transparency fields or detailed for bounded media and targeting arrays. Defaults to concise for agent-friendly output under the normal result cap. This is not a raw-provider-payload option and never exposes credentials. ## Actor input object example ```json { "advertisers": [ "Microsoft", "HubSpot" ], "keywords": [ "CRM software" ], "countries": [ "US", "DE" ], "startDate": "2026-01-01", "endDate": "2026-06-30", "maxResults": 20, "maxPagesPerSearch": 2, "fetchAdDetails": true, "providerPreference": "scrapecreators-first", "responseFormat": "concise" } ``` # Actor output Schema ## `ads` (type: `string`): Dataset records with advertiser, creative, destination, and eligible transparency fields. ## `output` (type: `string`): Compact terminal outcome and persisted-record counts. ## `runSummary` (type: `string`): Detailed provider attempts, pagination progress, warnings, and event charges. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "advertisers": [ "Microsoft" ] }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/linkedin-ad-library-search-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "advertisers": ["Microsoft"] } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/linkedin-ad-library-search-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "advertisers": [ "Microsoft" ] }' | apify call khadinakbar/linkedin-ad-library-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/linkedin-ad-library-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "LinkedIn Ad Library Search Scraper", "description": "Search public LinkedIn Ad Library ads by advertiser or keyword, with normalized creatives and EU transparency fields.", "version": "1.1", "x-build-id": "OEK71puh789dI1WRJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~linkedin-ad-library-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-linkedin-ad-library-search-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~linkedin-ad-library-search-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-linkedin-ad-library-search-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~linkedin-ad-library-search-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-linkedin-ad-library-search-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": { "advertisers": { "title": "Advertiser names", "type": "array", "description": "Use this when you know the company or advertiser whose public ads you want to review. Enter a list of display names such as Microsoft or HubSpot. Defaults to Microsoft only when neither advertisers nor keywords is supplied. This is not a LinkedIn company URL or a private Campaign Manager account ID.", "default": [], "items": { "type": "string" } }, "keywords": { "title": "Creative keywords", "type": "array", "description": "Use this when you want public ads whose creative matches a phrase instead of one known advertiser. Enter plain keywords such as CRM software or data warehouse. Defaults to no keyword searches, and each keyword becomes an independent search. This is not a Boolean LinkedIn profile query or a list of campaign IDs.", "default": [], "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Use this when results should be limited to countries reported by the Ad Library. Enter ISO alpha-2 codes such as US, DE, or GB. Defaults to no country filter, while supplied codes are sent together to each search. This is not a proxy location setting or a city-level targeting filter.", "default": [], "items": { "type": "string" } }, "startDate": { "title": "Start date", "type": "string", "description": "Use this when limiting ads by the beginning of their reported run window. Enter an ISO date such as 2026-01-01. Defaults to no lower date boundary and may be used with or without an end date. This is not a timestamp, a relative date phrase, or a campaign launch prediction.", "default": "" }, "endDate": { "title": "End date", "type": "string", "description": "Use this when limiting ads by the end of their reported run window. Enter an ISO date such as 2026-06-30. Defaults to no upper date boundary and must not be before startDate when both are supplied. This is not an expiry estimate or a relative date phrase.", "default": "" }, "maxResults": { "title": "Maximum ad records", "type": "integer", "description": "Use this to cap the number of normalized ad records saved and billed in this run. Enter an integer such as 20 between 1 and 100. Defaults to 20, which also caps the primary event charge before platform usage. This is not a page number or a guarantee that the Ad Library contains that many matches.", "default": 20 }, "maxPagesPerSearch": { "title": "Maximum pages per search", "type": "integer", "description": "Use this to bound provider pagination for every advertiser or keyword search. Enter an integer such as 2 between 1 and 10. Defaults to 1 page so the actor remains fast and cost-predictable. This is not an overall record limit because maxResults controls persisted ads.", "default": 1 }, "fetchAdDetails": { "title": "Fetch optional details", "type": "boolean", "description": "Use this when you need a second verified provider call per saved ad for richer public transparency data. Set true to request details and false to use the normalized search response only. Defaults to true and adds the documented detail-enrichment event only after a successful detail fetch. This is not a request for private advertiser, member, or Campaign Manager data.", "default": true }, "providerPreference": { "title": "Provider preference", "enum": [ "scrapecreators-first", "sociavault-first" ], "type": "string", "description": "Use this to choose which configured public-data provider is attempted first. Select scrapecreators-first or sociavault-first. Defaults to scrapecreators-first, and the other configured provider is tried after a route failure. This is not a user API key field or a promise that one provider has private LinkedIn data.", "default": "scrapecreators-first" }, "responseFormat": { "title": "Response format", "enum": [ "concise", "detailed" ], "type": "string", "description": "Use this to choose the token budget of each saved ad record. Select concise for core creative and transparency fields or detailed for bounded media and targeting arrays. Defaults to concise for agent-friendly output under the normal result cap. This is not a raw-provider-payload option and never exposes credentials.", "default": "concise" } } }, "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 } } } } } } } } } } ```