Name: LinkedIn Ad Library API for B2B Competitor Ads
Brand: unseen-user
SKU: api-unseen-user-linkedin-ad-library
Availability: InStock
Author: API Market

Unseen User

# LinkedIn Ad Library API

## Overview

The LinkedIn Ad Library API searches LinkedIn's public Ad Library and returns ads as structured JSON. One endpoint takes any mix of company names, keywords, LinkedIn company IDs, Ad Library search links and single-ad links; each value runs as its own search, and the results are merged and de-duplicated by ad ID. Each request runs a live scrape at call time, so the data reflects what LinkedIn is publishing at that moment. No LinkedIn account, login or cookies are needed.

It is built for B2B marketers, agencies, growth teams and researchers who want competitor LinkedIn ads in their own database or workflow. Each row in `data` is one ad with its ID and Ad Library link, advertiser and poster, headline, body copy, call to action, destination and landing page URLs, format, image, video or carousel media, run dates and days running, the targeting and impression disclosures LinkedIn publishes, and which input surfaced it. Optional switches fetch full ad details, attach advertiser company profiles and add AI classification with your own Anthropic key.

## Features

*   **1 endpoint**: `POST /v1/linkedin-ads` runs every search in the request and returns one merged result set.
*   **Bulk inputs**: Search by `companies`, `keywords` or `companyIds`, paste Ad Library search links in `searchUrls`, or fetch specific ads with `adUrls`. Every value runs its own search.
*   **Live scrape of the public Ad Library**: Every request collects data at call time. No login or cookies are involved.
*   **Filters**: Countries, date range and ad formats, applied to every search.
*   **Volume controls**: A global cap with `maxResults` and a per-search cap with `maxResultsPerQuery`. One call returns up to 100 rows.
*   **Full ad details**: Set `fetchAdDetails` to fetch the full ad page for every result, including headline, call to action, destination URL and targeting.
*   **Advertiser profiles**: Set `enrichAdvertisers` to attach industry, company size, employee count, founding year, website and headquarters to each ad, plus an advertisers table in `extras`.
*   **Rate limit**: 2 requests per second on every plan.

## Use Cases

*   **B2B competitor research**: See what each competitor is running on LinkedIn, with copy, creative, call to action and targeting in one result set.
*   **Agency creative briefs**: Build a swipe file of competitor ads to support pitches and campaign planning.
*   **Category discovery**: Search by keyword to find advertisers in a category, not only the brands you already know.
*   **Competitor ad tracking**: Call the API on a schedule and compare ad `id` values to catch new ads.
*   **Brand-safety monitoring**: Find third-party ads that use your brand name.
*   **Transparency research**: Pull LinkedIn's public ad disclosures for regulatory or journalistic work.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/unseen-user/linkedin-ad-library
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Search the LinkedIn Ad Library

Runs one search for each company name, keyword, company ID and link you send, and returns the matching ads as rows in `data`. Send at least one value across `companies`, `keywords`, `companyIds`, `searchUrls` or `adUrls`. The response always has the shape `{ "success": true, "data": [...], "meta": {...}, "extras": {...} }`, where `meta` carries the count and run information and `extras` carries the advertisers table when `enrichAdvertisers` is on. In our test, a 5-ad company search returned in about 9 seconds.

**Method:** `POST`

**Endpoint:** `/v1/linkedin-ads`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `companies` | body | Company names. Each name runs its own search. Names are matched as text, so a search returns every advertiser whose name contains the term. | array of strings | No | `[]` | - |
| `keywords` | body | Words or phrases. Each keyword runs its own search. | array of strings | No | `[]` | - |
| `companyIds` | body | Numeric LinkedIn company IDs, the reliable way to target one exact advertiser. The ID is the number at the end of `advertiserLinkedinPage` (for example `1035`). Each ID runs its own search. | array of strings | No | `[]` | - |
| `countries` | body | Two-letter country codes such as `US`, `GB` or `DE`. Only ads targeted at these countries are kept. Empty means all countries. | array of strings | No | `[]` | - |
| `startDate` | body | Only include ads that ran on or after this date, as `YYYY-MM-DD`. | string | No | - | - |
| `endDate` | body | Only include ads that ran on or before this date, as `YYYY-MM-DD`. | string | No | - | - |
| `maxResults` | body | Global cap across all searches; `0` returns every ad found. | integer | No | `0` | 100 rows per call |
| `maxResultsPerQuery` | body | Cap for each individual search (one company, keyword or company ID); `0` means no per-search limit. Stops one large advertiser from using the whole global cap. | integer | No | `0` | 100000 |
| `adTypes` | body | Ad formats to keep. Empty keeps all formats. Filtering happens after the search, so a rare format needs many more searches to reach the same number of results. | array of strings | No | `[]` | - |
| `fetchAdDetails` | body | Also fetch the full ad page for every result: headline, description, destination URL, call to action and targeting. Slower. | boolean | No | `false` | - |
| `enrichAdvertisers` | body | Attach advertiser company profiles (`advertiserIndustry`, `advertiserSize`, `advertiserEmployeeCount`, `advertiserFounded`, `advertiserType`, `advertiserWebsite`, `advertiserHeadquarters`, `b2bIntentScore`) to each ad, plus an advertisers table in `extras`. One lookup per company, not per ad. | boolean | No | `false` | - |
| `anthropicApiKey` | body | Your own Anthropic API key. When set, each ad gets `creativeAngle`, `creativeAngleConfidence` and `inferredAudience`, and each advertiser row gets `advertiserStrategy`. Billed to your Anthropic account. Leave empty to skip AI enrichment. | string | No | - | - |
| `aiModel` | body | Model for AI enrichment: `claude-haiku-4-5`, `claude-sonnet-5` or `claude-opus-5`. Used only when `anthropicApiKey` is set. | string | No | `claude-haiku-4-5` | - |
| `concurrency` | body | How many ad detail fetches run in parallel. | integer | No | `5` | 20 |
| `searchUrls` | body | LinkedIn Ad Library links copied from your browser. A search link (`linkedin.com/ad-library/search?...`) has its filters read off the URL; a single-ad link is fetched directly. Values in the other fields take priority. | array of strings | No | `[]` | - |
| `adUrls` | body | Single-ad links (`https://www.linkedin.com/ad-library/detail/<id>`), fetched directly and in full before any searches run. Other link types are skipped. | array of strings | No | `[]` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/unseen-user/linkedin-ad-library/v1/linkedin-ads" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companies":["microsoft"],"maxResults":5,"maxResultsPerQuery":5}'
```

**Example Response (200 OK, abridged to the first of 5 ads):**

```json
{
  "success": true,
  "data": [
    {
      "id": "1578061203",
      "adLibraryUrl": "https://www.linkedin.com/ad-library/detail/1578061203",
      "advertiser": "ScriptRunner - The #1 Microsoft Automation Platform",
      "poster": "ScriptRunner - The #1 Microsoft Automation Platform",
      "headline": "Is your stack a FrankenScript? \ud83c\udf83 Take the 5-question check",
      "description": "It runs. Nobody can fully explain, own or audit it. Answer 5 quick questions to see if your PowerShell automation has become a FrankenScript.",
      "cta": "Learn more",
      "destinationUrl": "https://www.scriptrunner.com/resources/frankenscript?utm_campaign=FrankenScript&utm_source=linkedin&utm_medium=paidsocial&utm_term=landing%20page&utm_content=frankenscript&utm_id=1116803843&hsa_acc=503112669&hsa_cam=1116803843&hsa_grp=896177783&hsa_ad=1578061203&hsa_net=linkedin&hsa_ver=3&trk=ad_library_ad_preview_headline_content",
      "adType": "Single Image Ad",
      "image": "https://media.licdn.com/dms/image/v2/D4D10AQERZVMkR8rdxQ/image-shrink_1280/B4DaE12LyTLAAc-/0/1791904759163/1png?e=2147483647&v=beta&t=4vMzsaH0aPPTVqQufFqdmzhzOlmGlWb6qjOrmLxLBvI",
      "startDate": "2026-10-13T00:00:00.000Z",
      "endDate": "2026-10-15T00:00:00.000Z",
      "adDuration": "Ran from Oct 13, 2026 to Oct 15, 2026",
      "daysRunning": 3,
      "targetingLocation": "Targeting includes Germany, Switzerland and\n      \n        8 others\n      \n      Netherlands, Benelux, DACH, United States, Canada, Austria, Belgium, United Kingdom",
      "targetingLanguage": "Targeting includes English",
      "advertiserLinkedinPage": "https://www.linkedin.com/company/16217038",
      "posterTitle": "Promoted",
      "carouselImages": [],
      "url": "https://www.linkedin.com/ad-library/detail/1578061203",
      "creativeType": "SPONSORED_STATUS_UPDATE",
      "advertiserLogo": "https://media.licdn.com/dms/image/v2/C4D0BAQFYeG3JIAlUQg/company-logo_100_100/company-logo_100_100/0/1630544718632/scriptrunner_logo?e=1793836800&v=beta&t=hinK00WmPJl39G_SyAyjJU6NeCkuwn9vOtmG3bCfdSw",
      "sponsoredMessageButtons": [],
      "landingPage": "https://www.scriptrunner.com/resources/frankenscript?utm_campaign=FrankenScript&utm_source=linkedin&utm_medium=paidsocial&utm_term=landing%20page&utm_content=frankenscript&utm_id=1116803843&hsa_acc=503112669&hsa_cam=1116803843&hsa_grp=896177783&hsa_ad=1578061203&hsa_net=linkedin&hsa_ver=3&trk=ad_library_ad_preview_headline_content",
      "totalImpressions": "< 1k",
      "impressionsByCountry": [
        {
          "country": "Netherlands",
          "impressions": "28%"
        },
        {
          "country": "United Kingdom",
          "impressions": "26%"
        },
        {
          "country": "Germany",
          "impressions": "16%"
        },
        {
          "country": "Switzerland",
          "impressions": "9%"
        },
        {
          "country": "Belgium",
          "impressions": "9%"
        },
        {
          "country": "United States",
          "impressions": "7%"
        },
        {
          "country": "Austria",
          "impressions": "2%"
        },
        {
          "country": "Luxembourg",
          "impressions": "1%"
        },
        {
          "country": "Canada",
          "impressions": "1%"
        }
      ],
      "_searchedByField": "company",
      "_searchedByValue": "microsoft",
      "_scrapedAt": "2026-10-15T21:51:28.509Z"
    }
  ]
}
```

**Main fields in each ad row:**

*   **Identity**: `id`, `adLibraryUrl`, `url`, `advertiser`, `advertiserLinkedinPage`, `advertiserLogo`.
*   **Poster**: `poster`, `posterTitle` and `promotedBy` (set on Thought Leader Ads, where `poster` is a person and `advertiser` is the brand).
*   **Copy and call to action**: `headline`, `description`, `cta`, `destinationUrl`, `landingPage`.
*   **Format and media**: `adType` (for example `Single Image Ad`, `Video Ad`, `Carousel Ad`, `Document Ad`, `Event Ad`), `creativeType`, `image`, `video`, `organicVideo`, `carouselImages[]`.
*   **Timing**: `startDate`, `endDate`, `adDuration`, `daysRunning`.
*   **Disclosures**: `targetingLocation`, `targetingLanguage`, `targetingAudience`, `totalImpressions` (a bucket such as `< 1k`) and `impressionsByCountry` (percentage shares).
*   **Traceability**: `_searchedByField`, `_searchedByValue`, `_sourceUrl` (for ads fetched from a link) and `_scrapedAt`.

Empty fields are removed from each row. LinkedIn publishes less detail for some formats, so Video Ads and Document Ads carry fewer fields than Single Image Ads.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request ran and the ads are in `data`. If a search found nothing or the data source failed, `data` holds an explanation row with `error` and `message` fields instead of ad data. |
| 400 | Bad Request | The body is invalid, for example a field has the wrong type or a value outside its allowed options. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path is wrong. Use `POST /v1/linkedin-ads`. |
| 429 | Too Many Requests | You went over 2 requests per second, or you used up your plan's request quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The scrape could not be completed. Retry the request. |
| 503 | Service Unavailable | The service is busy or temporarily unavailable. Retry shortly. |
| 504 | Gateway Timeout | The scrape took too long. Calls stop after about 150 seconds; ask for fewer ads and try again. |

## Rate Limits

The Free, Basic, Pro, Ultra and Mega plans all allow 2 requests per second. The Free plan includes 25 requests and stops there; upgrade to a paid plan to keep going. Each request runs a live scrape that took about 9 seconds in our test, so send requests in sequence or with low concurrency. Requests above the limit return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header.

## FAQ

**Why does a company name search return other advertisers?**

Company names are matched against advertiser names as text, so every advertiser whose name contains your term comes back, including partners and resellers. Check `advertiser` and `advertiserLinkedinPage` on each row. To target one exact advertiser, send its numeric ID in `companyIds`; the ID is the number at the end of `advertiserLinkedinPage`.

**Why do some ads have no headline or call to action?**

LinkedIn publishes different detail for different formats. Single Image Ads carry the most; Video Ads and Document Ads carry the least. Set `fetchAdDetails` to `true` to fetch everything LinkedIn exposes for each ad.

**Does it return impressions and targeting?**

Where LinkedIn publishes them. `totalImpressions` is a bucket such as `< 1k` or `5k-10k`, and `impressionsByCountry` gives percentage shares by country. `targetingLocation`, `targetingLanguage` and `targetingAudience` carry LinkedIn's disclosure text, not the advertiser's exact campaign setup.

**What is an explanation row?**

When a search finds nothing or the data source fails, `data` holds a row with an `error` code (`NO_RESULTS`, `NO_SEARCH_INPUT`, `AUTH_FAILED`, `UPSTREAM_UNAVAILABLE`, `NO_RESULTS_ALL_SKIPPED`, `NOT_CONFIGURED` or `UNEXPECTED_ERROR`) and a plain `message`. Ad rows never carry these fields, so skip any row where `error` is set. Ads already collected before a failure are still returned.

**What is the difference between `adUrls` and `searchUrls`?**

`adUrls` takes single-ad links (`/ad-library/detail/<id>`) only and skips anything else. `searchUrls` takes Ad Library search links and reads their filters, and also accepts single-ad links, so send a link there if you are unsure which kind it is.

**How many ads can one call return?**

Up to 100 rows. Use `maxResultsPerQuery` so one large advertiser does not use the whole call, and split bigger jobs across several calls by company, keyword, country or date range. The Ad Library covers roughly the last year of ads.

**How does the optional AI enrichment work?**

Add your own Anthropic API key in `anthropicApiKey`. Each ad gets a `creativeAngle` (such as `thought_leadership`, `lead_magnet`, `product_demo`, `hiring`, `event`, `brand_awareness`, `customer_proof` or `offer`), a confidence level and an `inferredAudience` based only on the ad's wording. That usage is billed to your Anthropic account. If the key is wrong or the AI service is unavailable, the ads come back without these fields.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


LinkedIn Ad Library API that returns ads by company, keyword or company ID, with headlines, copy, CTAs, destination URLs, targeting and run dates.

LinkedIn Ad Library API for B2B Competitor Ads

Free