LinkedIn Ad Library Scraper – API Integration Guide

This document describes the Actor's inputs and outputs for AI agents building API connections to this Actor. Use it to prepare correct request payloads and consume response data.

---

Overview

Actor name: linkedin-ad-library-scraper
What it does: Searches LinkedIn Ad Library by filters (advertiser, keyword, country, dates) and optionally scrapes each ad's detail page for full metadata (impressions, targeting, country split).

Apify API base: https://api.apify.com/v2

---

Running the Actor via API

1. Start a run

POST https://api.apify.com/v2/acts/{USERNAME}~linkedin-ad-library-scraper/runs
Authorization: Bearer {APIFY_TOKEN}
Content-Type: application/json
{
  "keyword": "JetBrains",
  "country": "DE",
  "maxResults": 20,
  "scrapeAdDetails": true
}

Replace {USERNAME} with the Apify account username and {APIFY_TOKEN} with a valid API token.

2. Poll for completion

GET https://api.apify.com/v2/actor-runs/{runId}
Authorization: Bearer {APIFY_TOKEN}

Response includes status (RUNNING | SUCCEEDED | FAILED | ABORTED). When status is SUCCEEDED, fetch the output.

3. Fetch results

Dataset (scraped ads):

GET https://api.apify.com/v2/datasets/{defaultDatasetId}/items
Authorization: Bearer {APIFY_TOKEN}

Run summary (metadata):

GET https://api.apify.com/v2/key-value-stores/{defaultKeyValueStoreId}/records/OUTPUT
Authorization: Bearer {APIFY_TOKEN}

defaultDatasetId and defaultKeyValueStoreId are in the run response when the run succeeds.

---

Input Schema

Send a JSON object as the request body. All fields are optional, but at least one of these must be provided: detailUrls, companyOrAdvertiser, payer, or keyword.

Search filters (choose at least one when not using detailUrls)

Field	Type	Description	Example
companyOrAdvertiser	string	Filter by advertiser or company name	"JetBrains"
payer	string	Filter by paying organization	"Acme Corp"
keyword	string	Search keyword for ads	"developer tools"

Direct URLs (bypasses search)

Field	Type	Description	Example
detailUrls	string[]	Scrape these ad detail URLs directly. Bypasses search.	["https://www.linkedin.com/ad-library/detail/1191832683"]

Additional search filters

Field	Type	Default	Description	Example
country	string	—	Country filter (2-letter code). Used for country-specific impressions.	"DE"
datePreset	string	"this-year"	Date range preset. Options: "last-30-days", "this-month", "this-year", "last-year"	"this-year"
startDate	string	—	Custom start date (YYYY-MM-DD). Overrides datePreset when used with endDate.	"2025-01-01"
endDate	string	—	Custom end date (YYYY-MM-DD).	"2025-12-31"

Scraping options

Field	Type	Default	Description
maxResults	integer	10	Max number of ads to scrape. Min: 1, Max: 100000.
batchSize	integer	50	Number of items to push to dataset before flush. Min: 1, Max: 2000.
scrapeAdDetails	boolean	true	Visit each ad detail page for full metadata (impressions, targeting, country split).
readImages	boolean	false	Use OCR to extract text from ad images.
useProxy	boolean	false	Use Apify proxy. Recommended to reduce LinkedIn blocks (403).

Authentication

Field	Type	Description
authCookies	object[]	LinkedIn session cookies for authenticated scraping. Each object: { name, value, domain?, path? }.

---

Input examples

Search by keyword and country:

{
  "keyword": "JetBrains",
  "country": "DE",
  "maxResults": 50,
  "scrapeAdDetails": true,
  "useProxy": true
}

Direct URLs only (no search):

{
  "detailUrls": [
    "https://www.linkedin.com/ad-library/detail/1191832683",
    "https://www.linkedin.com/ad-library/employer-brand/1234567"
  ],
  "scrapeAdDetails": true
}

Search by advertiser with custom dates:

{
  "companyOrAdvertiser": "kt.academy",
  "startDate": "2025-01-01",
  "endDate": "2025-03-15",
  "maxResults": 100
}

---

Output Schema

Dataset (array of ad objects)

Each dataset item is a flat object with these fields. All fields are strings unless noted. Empty or missing values are often "".

Field	Type	Description	Example
adId	string	LinkedIn ad identifier	"1191832683"
adDetailUrl	string	Direct link to ad in LinkedIn Ad Library	"https://www.linkedin.com/ad-library/detail/1191832683"
advertiserName	string	Advertiser or company name	"kt.academy"
advertiserUrl	string	Link to advertiser's LinkedIn company page
advertiserLogoUrl	string	URL of advertiser logo
adFormat	string	Ad type	"Single Image Ad"
headline	string	Ad headline
bodyText	string	Main ad copy from detail page
searchResultsAdText	string	Ad text as shown on search results
primaryImageUrl	string	URL of main ad image
ctaText	string	Call-to-action button text
startDate	string	When ad started running	"Mar 9, 2026"
endDate	string	When ad stopped running	"Mar 15, 2026"
totalImpressionsInterval	string	Impressions range as shown	"1k-5k", "20k-30k"
impressionRange	string	Same as totalImpressionsInterval (legacy)
paidBy	string	Organization that paid for the ad
targetingLanguage	string	Target language settings
targetingLocation	string	Target location settings
TargetingAudience	string	"Targeted" | "Excluded" | "Targeted and Excluded" | "Not Used"
TargetingDemographics	string	Same enum
TargetingCompany	string	Same enum
TargetingEducation	string	Same enum
TargetingJob	string	Same enum
TargetingInterests	string	Same enum
allCountriesImpressionsLowerBound	integer | string	Numeric lower bound from interval	1000
allCountriesImpressionsUpperBound	integer | string	Numeric upper bound from interval	5000
countrySplit	string	Country and percentage pairs	`"Germany
countryShare	string	Target country's percentage when filter used
countryImpressionsLowerBound	string	Lower bound for target country
countryImpressionsUpperBound	string	Upper bound for target country
carouselImageUrls	string	Carousel image URLs
documentPageUrls	string	Document ad page URLs
videoUrl	string	Video ad URL
adTextOcr	string	Text from ad images via OCR (if readImages enabled)
scrapedAt	string	ISO 8601 timestamp when item was scraped	"2026-03-15T04:30:00.000Z"

Run summary (key-value store record OUTPUT)

{
  "totalAds": 20
}

totalAds is the number of unique ads scraped.

---

Output URLs (from run response)

After a successful run, the run object contains:

• defaultDatasetId – use to fetch items: GET .../datasets/{defaultDatasetId}/items
• defaultKeyValueStoreId – use to fetch OUTPUT: GET .../key-value-stores/{defaultKeyValueStoreId}/records/OUTPUT

Or use the output schema templates from the run:

• Dataset items: {links.apiDefaultDatasetUrl}/items
• Run summary: {links.apiDefaultKeyValueStoreUrl}/records/OUTPUT

---

Validation rules (API client)

1. At least one of: detailUrls (non-empty), companyOrAdvertiser, payer, or keyword must be set.
2. Dates: If startDate or endDate is set, both should be set. Format: YYYY-MM-DD.
3. detailUrls: Each URL should be a LinkedIn ad library URL (/ad-library/detail/ or /ad-library/employer-brand/).
4. authCookies: If provided, each cookie must have name and value.

---

Error handling

• Run status: "FAILED" – check run stats and logs for the cause.
• Empty dataset – no ads matched filters, or LinkedIn returned errors (try useProxy: true or authCookies).
• ERR_HTTP_RESPONSE_CODE_FAILURE – LinkedIn blocking (403) or ad gone (404). Enable proxy or reduce maxResults.