> ## 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 广告资料库 API

> 从 LinkedIn 广告资料库以 JSON 分析竞品广告：按关键词、广告主或付费方搜索广告，并可打开单条广告，获取资料库公开的付费方、展示次数和触达的国家。

通过异步 task API 读取 LinkedIn 广告资料库，以 JSON 获取竞品向职场人群投放了哪些广告。ADS 是独立的引擎。向 `taskType` `ADS` 发送 `platform` `linkedin_ad_library`，并用 `action` 选择要读取的内容。要在各广告资料库之间选择，参见 [广告资料库对比](https://docs.querying.ai/zh/engines/ad-libraries.md)。

* `search`（默认）按 `query` 中的关键词、`advertiserName` 中的广告主名称、`payer` 中的付费方，或它们的组合来列出广告。每条广告带有广告主、形式、标题、文案和媒体，响应末尾附有汇总所返回广告的 `summary`。
* `ad` 打开单条广告：返回广告主、付费方、落地页，以及资料库公开时的投放日期、展示次数、触达的国家和定向。

资料库没有广告主查找功能，所以 `action` `advertisers` 会以 `400 VALIDATION_ERROR` 拒绝。请在搜索中用 `advertiserName` 查找竞品。

搜索按返回的**每 30 条广告收取 0.5 积分**。`ad` 收取 0.5 积分。

## 请求

```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 } }'
```

提交 task 后，轮询 `GET /v1/async/task/{id}` 或通过 webhook 接收。参见 [异步 task](https://docs.querying.ai/zh/concepts/async-tasks.md)。资料库限制读取速度，所以 120 条广告的搜索约需半分钟。

## 分析竞品广告

三个请求即可完成一次竞品分析：

1. 把竞品名称放入 `advertiserName` 发送 `search`，列出它的广告。`advertiserName` 匹配名称的一部分，因此请检查每条广告的 `advertiserName`。加上 `query` 可把广告缩小到某个主题，用 `sortBy` `oldest` 从最早的广告开始。
2. 用广告的 `libraryId` 发送 `ad`，得到付费方和落地页；对于在欧盟展示的广告，还有投放日期、展示次数和定向。
3. 用 `payer` 发送 `search`，列出某家代理公司或企业付费的广告，无论由哪个主页投放。

## 参数

* `action`：`search`（默认）或 `ad`。
* `query`：广告文案中的关键词。`search` 需要 `query`、`advertiserName` 或 `payer`。
* `advertiserName`：名称，按广告主名称的一部分匹配，例如 `samsung`。
* `payer`：付费方的名称，按名称的一部分匹配，例如 `Starcom`。
* `libraryId`：广告的数字 ID，例如 `1638962914`。`ad` 必须提供。
* `country`：广告展示的国家，用两位国家代码表示，`ALL` 表示所有国家（默认）。
* `startDate`、`endDate`：`YYYY-MM-DD`，需同时发送，且在最近一年内。保留在这两天之间展示的广告。
* `sortBy`：`newest`（默认）或 `oldest`。
* `limit`：1 到 120 条广告。默认 30。
* `cursor`：上一次响应的 `nextCursor`，用于读取其后的广告。

`search` 读取上面除 `libraryId` 之外的所有字段，`ad` 只读取 `libraryId`。Meta 广告资料库的筛选字段（`pageId`、`pageIds`、`activeStatus`、`searchType`、`adType`、`mediaType`、`publisherPlatforms` 或 `contentLanguages`）、资料库无法搜索的值，或该操作不读取的字段，会以 `400 VALIDATION_ERROR` 拒绝，`details` 会指明字段。

## 读取更多广告

还有更多广告可读时，响应带有 `nextCursor`。把它作为 `cursor` 与同一搜索一起发送，即可收到后续广告，同样最多 `limit` 条。资料库没有更多广告时，`nextCursor` 为 `null`。游标只能用于返回它的那次搜索：`query`、`advertiserName`、`payer`、`country`、日期范围或 `sortBy` 不同，会以 `400 VALIDATION_ERROR` 拒绝，而 `limit` 可以改变。

## 搜索响应示例

```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
  }
}
```

* 响应会原样返回 `platform`、`action`、`country`、`query`、`advertiserName`、`payer`、`sortBy` 以及你传入的日期。`returnedCount` 统计 `ads` 中的广告数，资料库还有更多广告时 `hasMore` 为 `true`，可用 `nextCursor` 继续读取，`libraryUrl` 在广告资料库中打开同一搜索。资料库不给出总数，所以 `totalCount` 为 `null`。
* 每条广告是一张卡片：`position`、`libraryId`、`libraryUrl`、`advertiserName`、`advertiserLogoUrl`、`creativeType`（如 `SPONSORED_STATUS_UPDATE` 或 `SPONSORED_VIDEO`）、`format`、`title`、`body`、`images`、`videos`（视频封面在 `previewUrl`）和 `platforms`（`LINKEDIN`）。`format` 为 `IMAGE`、`VIDEO`、`CAROUSEL`、`DOCUMENT`、`ARTICLE`、`MESSAGE`、`JOB`、`SPOTLIGHT` 或 `FOLLOW_COMPANY`。
* 消息广告和 Thought Leader 广告带有 `member`，即消息的发送者或广告所推广帖子的作者，包含 `name` 和 `url`；`ad` 以相同的结构返回。其他广告的 `member` 为 `null`。
* 卡片包含文案的前 120 个字符，文案更长时 `bodyTruncated` 为 `true`。`ad` 返回完整文案。
* `advertiserId`、`payer`、`startDate`、`endDate`、`activeDays`、`linkUrl`、`landingDomain`、`impressions`、`targeting`、`ctaText` 和 `utm` 在卡片上为 `null`，由 `ad` 填充资料库中有的值。资料库不说明广告是否仍在投放，所以 `isActive` 为 `null`。
* `summary` 统计本次响应中的广告：`ads`、`advertisers`（广告最多的 10 个：`advertiserName`、`ads`）、`formats` 和 `platforms`。卡片不含日期，所以它的日期字段（`oldestStartDate`、`newestStartDate`、`medianActiveDays`、`launchesByWeek` 和 `longestRunning`）保持为空或 `null`。
* 没有匹配广告的搜索会以空的 `ads` 和广告数为 `0` 的 `summary` 完成。

## 资料库保留的范围

* 每条广告的素材、广告主和付费方在所有国家都可获取。
* 投放日期、展示次数范围、各国展示次数占比和定向，仅对在欧盟展示的广告可获取。
* 资料库保留广告约 12 个月，日期筛选只接受最近一年。

## 打开单条广告

`action` `ad` 打开你发送的 `libraryId` 对应的广告，可从搜索结果或广告资料库地址 `/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` 包含带完整文案的搜索卡片的字段，外加 `advertiserId`、`advertiserUrl`、`advertiserType`（`company` 或 `person`）、`payer`（为广告付费的一方）、`linkUrl`、`landingDomain`、`ctaText`、`startDate`、`endDate`、`activeDays`、`impressions`、`targeting` 和 `reachedCountries`。
* `impressions` 是资料库公开的范围（`min`、`max`）。`targeting` 列出广告主包含或排除的语言和地区（`language`、`location`）以及定向参数（`parameters`：`parameter`、`targeted`、`excluded`）。对于未在欧盟展示的广告，例如 Adobe 的广告 `1698237666`，日期、`impressions`、`targeting` 和 `reachedCountries` 为 `null`。付费方和广告主则每条广告都有。
* `videos` 列出每个视频的 `url`（码率最高的文件）、`files`（所有 mp4：`url`、`type`、`bitrate`）和 `previewUrl`。轮播广告增加 `cards`（`title`、`imageUrl`），文档广告增加 `document`（标题、页数和各页封面）。
* `advertiser` 是广告背后的主页：`advertiserId`、`advertiserName`、`url`、`type` 和 `logoUrl`。
* 未在欧盟展示的广告，`transparency` 为 `null`。在欧盟展示的广告则包含 `impressions`、`impressionsText`（资料库给出的文字，如 `50k-100k`）和 `reachByCountry`，即各国展示次数的占比（`country`、`countryCode`、`share`、`shareText`），欧盟以外的国家也包含在内。
* `variants` 在资料库显示多个版本时列出广告的其他版本，否则为 `null`。
* 素材的媒体 URL 多年保持可访问。轮播卡片的 URL 约一周后过期，广告主标志约两周半后过期。请自行保存需要的文件。
* 资料库没有对应广告的 `libraryId` 会以 `PAGE_UNAVAILABLE` 失败。

## 价格

搜索开始时，按 `limit` 所要求的每 30 条广告预留 0.5 积分，按实际返回的每 30 条广告收取 0.5 积分，最少 0.5 积分。默认搜索（30 条广告）收取 0.5 积分，`limit` 为 120 的搜索预留 2 积分。`ad` 收取 0.5 积分。只对已完成的请求收费。

## 相关

* [广告资料库对比](https://docs.querying.ai/zh/engines/ad-libraries.md)
* [Meta 广告资料库](https://docs.querying.ai/zh/engines/meta-ad-library.md)
* [引擎概览](https://docs.querying.ai/zh/engines/overview.md)
* [积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)


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