> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LinkedIn Ad Library API

> Analyze competitor ads from the LinkedIn Ad Library as JSON: search the ads by keyword, advertiser or payer, and open one ad for who paid, the impressions and the countries it reached where the library publishes them.

Read the LinkedIn Ad Library as JSON through the async task API, to see what your competitors advertise to professionals. ADS is its own engine: send `taskType` `ADS` with `platform` `linkedin_ad_library`, and `action` picks what to read. To choose between the ad libraries, see [Ad libraries compared](https://docs.querying.ai/engines/ad-libraries.md).

* `search` (default) lists ads by a keyword in `query`, by an advertiser's name in `advertiserName`, by who paid in `payer`, or by a combination. Each ad carries its advertiser, format, title, text and media, and the response ends with a `summary` of the ads it returned.
* `ad` opens one ad: the advertiser, who paid, the landing page, and where the library publishes it, the run dates, the impressions, the countries it reached and its targeting.

The library has no advertiser lookup, so `action` `advertisers` is rejected with `400 VALIDATION_ERROR`. Find a competitor with `advertiserName` in a search.

A search costs **0.5 credits for every 30 ads** it returns. `ad` costs 0.5 credits.

## Request

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "linkedin_ad_library", "query": "webinar", "country": "ALL", "limit": 30 } }'
```

Submit the task, then poll `GET /v1/async/task/{id}` or receive its webhook. See [Async tasks](https://docs.querying.ai/concepts/async-tasks.md). The library limits how fast it reads, so a search of 120 ads takes about half a minute.

## Analyze a competitor's ads

Three requests cover a competitor analysis:

1. `search` with the competitor's name in `advertiserName` lists its ads. `advertiserName` matches part of a name, so check `advertiserName` on each ad. Add `query` to narrow the ads to a topic, and `sortBy` `oldest` to start from the oldest ads.
2. `ad` with an ad's `libraryId` returns who paid, the landing page and, for ads shown in the EU, the run dates, the impressions and the targeting.
3. `search` with `payer` lists the ads an agency or company paid for, whichever page runs them.

## Parameters

* `action`: `search` (default) or `ad`.
* `query`: A keyword in the ad's text. `search` needs `query`, `advertiserName` or `payer`.
* `advertiserName`: A name, matched as part of the advertiser's name, such as `samsung`.
* `payer`: The name of who paid for the ad, matched as part of the name, such as `Starcom`.
* `libraryId`: The numeric ID of an ad, such as `1638962914`. `ad` requires it.
* `country`: Where the ads were shown, as a two-letter country code, or `ALL` for every country (default).
* `startDate`, `endDate`: `YYYY-MM-DD`, sent together, within the last year. Keeps the ads shown between the two days.
* `sortBy`: `newest` (default) or `oldest`.
* `limit`: 1 to 120 ads. Default 30.
* `cursor`: The `nextCursor` of an earlier response, to read the ads after it.

`search` reads every field above except `libraryId`, and `ad` reads `libraryId` only. A Meta Ad Library filter (`pageId`, `pageIds`, `activeStatus`, `searchType`, `adType`, `mediaType`, `publisherPlatforms` or `contentLanguages`), a value the library cannot search, or a field the action does not read is rejected with `400 VALIDATION_ERROR`, and `details` names the field.

## Read more ads

A response with more ads to read carries `nextCursor`. Send it as `cursor` with the same search to receive the next ads, again up to `limit`. `nextCursor` is `null` once the library has no more. A cursor works only with the search that returned it: a different `query`, `advertiserName`, `payer`, `country`, date range or `sortBy` is rejected with `400 VALIDATION_ERROR`, while `limit` can change.

## Search response

```json theme={"theme":"css-variables"}
{
  "platform": "linkedin_ad_library",
  "action": "search",
  "country": "ALL",
  "query": "webinar",
  "totalCount": null,
  "returnedCount": 30,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoielVmY24wUlRHU0hSWHYwYSIsImMiOiIxNjk4Mjc2MTc2LTE3OTUyMTAzMTIxMzkiLCJzIjo2LCJwIjozMH0",
  "libraryUrl": "https://www.linkedin.com/ad-library/search?keyword=webinar&countries=ALL",
  "ads": [
    {
      "position": 1,
      "libraryId": "1698500736",
      "libraryUrl": "https://www.linkedin.com/ad-library/detail/1698500736",
      "advertiserId": null,
      "advertiserName": "Rescale",
      "isActive": null,
      "startDate": null,
      "endDate": null,
      "activeDays": null,
      "platforms": ["LINKEDIN"],
      "format": "IMAGE",
      "title": "How engineering teams get AI agents past the pilot",
      "body": "Most engineering teams have tried AI agents. Far fewer have moved them past the pilot. Watch Kairos Power and Oak Ridge …",
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://media.licdn.com/dms/image/v2/D5610AQFdah1Z0xeBuQ/image-shrink_1280/B56aH7HH6kH4AY-/0/1795214311284/Fall2026-Showcase_LinkedIn_6A_Webinar-on-demand_1200x1200png"
      ],
      "videos": [],
      "advertiserLogoUrl": "https://media.licdn.com/dms/image/v2/D560BAQFsh4MOa0Ohiw/company-logo_100_100/B56Z4dQLnEIQAQ-/0/1778607242071/rescale_logo",
      "advertiserType": null,
      "advertiserUrl": null,
      "bodyTruncated": true,
      "creativeType": "SPONSORED_STATUS_UPDATE"
    }
  ],
  "summary": {
    "ads": 30,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "Rescale", "ads": 5 }
    ],
    "formats": { "ARTICLE": 1, "CAROUSEL": 1, "IMAGE": 24, "SPOTLIGHT": 2, "VIDEO": 2 },
    "platforms": { "LINKEDIN": 30 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [],
    "longestRunning": [],
    "oldestStartDate": null,
    "newestStartDate": null,
    "medianActiveDays": null
  }
}
```

* The response echoes `platform`, `action`, `country`, `query`, `advertiserName`, `payer`, `sortBy` and the dates it was given. `returnedCount` counts the ads in `ads`, `hasMore` is `true` when the library has more, which `nextCursor` reads, and `libraryUrl` opens the same search in the Ad Library. `totalCount` is `null`, because the library gives no count.
* Each ad is a card: `position`, `libraryId`, `libraryUrl`, `advertiserName`, `advertiserLogoUrl`, `creativeType` (such as `SPONSORED_STATUS_UPDATE` or `SPONSORED_VIDEO`), `format`, `title`, `body`, `images` and `videos` (the video's poster in `previewUrl`), and `platforms` (`LINKEDIN`). `format` is `IMAGE`, `VIDEO`, `CAROUSEL`, `DOCUMENT`, `ARTICLE`, `MESSAGE`, `JOB`, `SPOTLIGHT` or `FOLLOW_COMPANY`.
* Message ads and thought leader ads carry `member`, the sender of the message or the member whose post the ad promotes, as `name` and `url`; `ad` returns it in the same shape. `member` is `null` on other ads.
* A card carries the first 120 characters of the text, and `bodyTruncated` is `true` when the text is longer. `ad` returns the full text.
* `advertiserId`, `payer`, `startDate`, `endDate`, `activeDays`, `linkUrl`, `landingDomain`, `impressions`, `targeting`, `ctaText` and `utm` are `null` on a card. `ad` fills them where the library has them. `isActive` is `null`, because the library does not tell whether an ad still runs.
* `summary` counts the ads of this response: `ads`, `advertisers` (the 10 with the most ads: `advertiserName`, `ads`), `formats` and `platforms`. Its date fields (`oldestStartDate`, `newestStartDate`, `medianActiveDays`, `launchesByWeek` and `longestRunning`) stay empty or `null`, because cards carry no dates.
* A search with no matching ads completes with an empty `ads` and a `summary` of `0` ads.

## What the library keeps

* Every ad's creative, advertiser and payer are available for every country.
* The run dates, the impressions range, the share of impressions by country and the targeting are available only for ads shown in the EU.
* The library keeps ads for about 12 months, and its date filter takes only the last year.

## Open one ad

`action` `ad` opens the ad with the `libraryId` you send, from a search or from the Ad Library address `/ad-library/detail/<libraryId>`.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "linkedin_ad_library", "action": "ad", "libraryId": "1638962914" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "linkedin_ad_library",
  "action": "ad",
  "libraryId": "1638962914",
  "ad": {
    "libraryId": "1638962914",
    "libraryUrl": "https://www.linkedin.com/ad-library/detail/1638962914",
    "advertiserId": "85881048",
    "advertiserName": "Samsung Germany",
    "isActive": null,
    "startDate": "2026-11-11",
    "endDate": "2026-11-22",
    "activeDays": 12,
    "platforms": ["LINKEDIN"],
    "format": "VIDEO",
    "title": "Smart arbeiten mit der Galaxy Z-Serie",
    "body": "Mails mobil checken, aber für die eigentliche Arbeit genervt an den Laptop wechseln? Das bremst den Workflow.\n\nSpar dir den Medienbruch mit der neuen Galaxy Z-Serie und nutze die maximale Flexibilität unserer faltbaren Smartphones:\n\n📱 Z Fold8 Ultra: 8-Zoll-…",
    "ctaText": "Learn more",
    "ctaType": null,
    "linkUrl": "https://www.samsung.com/de/smartphones/galaxy-z-fold8/",
    "landingDomain": "samsung.com",
    "utm": null,
    "payer": "Starcom Germany GmbH",
    "impressions": { "min": 50000, "max": 100000 },
    "targeting": {
      "language": { "exclude": null, "include": ["English"] },
      "location": { "exclude": null, "include": ["Germany"] },
      "parameters": [
        { "excluded": false, "parameter": "Audience", "targeted": false }
      ]
    },
    "reachedCountries": ["DE"],
    "images": [],
    "videos": [
      {
        "bitrate": 12005128,
        "files": [
          {
            "bitrate": 12005128,
            "type": "video/mp4",
            "url": "https://dms.licdn.com/playlist/vid/v2/D4E10AQHs0oH-zSWScA/progressive-servable-video/B4EaHKwT54IoAg-/0/1794403027272"
          }
        ],
        "previewUrl": "https://media.licdn.com/dms/image/v2/D4E10AQHs0oH-zSWScA/videocover-high/B4EaHKwT54IoBQ-/0/1794403028674",
        "url": "https://dms.licdn.com/playlist/vid/v2/D4E10AQHs0oH-zSWScA/progressive-servable-video/B4EaHKwT54IoAg-/0/1794403027272"
      }
    ],
    "advertiserLogoUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQEL38Z5ttMZXw/company-logo_100_100/company-logo_100_100/0/1692353831724/samsung_germany_logo",
    "advertiserType": "company",
    "advertiserUrl": "https://www.linkedin.com/company/85881048",
    "bodyTruncated": false,
    "creativeType": "SPONSORED_VIDEO"
  },
  "advertiser": {
    "advertiserId": "85881048",
    "advertiserName": "Samsung Germany",
    "logoUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQEL38Z5ttMZXw/company-logo_100_100/company-logo_100_100/0/1692353831724/samsung_germany_logo",
    "type": "company",
    "url": "https://www.linkedin.com/company/85881048"
  },
  "transparency": {
    "impressions": { "min": 50000, "max": 100000 },
    "impressionsText": "50k-100k",
    "reachByCountry": [
      { "country": "Germany", "countryCode": "DE", "share": 100, "shareText": "100%" }
    ]
  },
  "variants": null
}
```

* `ad` has the fields of a search card with the full text, plus `advertiserId`, `advertiserUrl`, `advertiserType` (`company` or `person`), `payer` (who paid for the ad), `linkUrl`, `landingDomain`, `ctaText`, `startDate`, `endDate`, `activeDays`, `impressions`, `targeting` and `reachedCountries`.
* `impressions` is the range the library publishes (`min`, `max`). `targeting` lists the languages and locations the advertiser included or excluded (`language`, `location`) and the targeting parameters (`parameters`: `parameter`, `targeted`, `excluded`). The dates, `impressions`, `targeting` and `reachedCountries` are `null` for an ad that was not shown in the EU, such as the Adobe ad `1698237666`. The payer and the advertiser are there for every ad.
* `videos` lists each video with `url` (the file with the highest bitrate), `files` (every mp4: `url`, `type`, `bitrate`) and `previewUrl`. A carousel ad adds `cards` (`title`, `imageUrl`) and a document ad adds `document` (its title, page count and page covers).
* `advertiser` is the page behind the ad: `advertiserId`, `advertiserName`, `url`, `type` and `logoUrl`.
* `transparency` is `null` for an ad not shown in the EU. For an ad shown in the EU it holds `impressions`, `impressionsText` (the library's text, such as `50k-100k`) and `reachByCountry`, the share of the impressions in each country (`country`, `countryCode`, `share`, `shareText`), outside the EU too.
* `variants` lists the other versions of the ad where the library shows more than one, and is `null` otherwise.
* Media URLs of creatives stay open for years. The URLs of carousel cards expire after about a week, and advertiser logos after about two and a half weeks. Save the files you need.
* A `libraryId` the library has no ad for fails with `PAGE_UNAVAILABLE`.

## Price

A search holds 0.5 credits for every 30 ads its `limit` asks for, and is charged 0.5 credits for every 30 ads it returns, at least 0.5 credits. The default search of 30 ads costs 0.5 credits, and a search with `limit` 120 holds 2 credits. `ad` costs 0.5 credits. Only completed requests are charged.

## Related

* [Ad libraries compared](https://docs.querying.ai/engines/ad-libraries.md)
* [Meta Ad Library](https://docs.querying.ai/engines/meta-ad-library.md)
* [Engine overview](https://docs.querying.ai/engines/overview.md)
* [Credits and limits](https://docs.querying.ai/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.