> ## 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으로 분석합니다. 키워드, 광고주, 광고비를 낸 주체로 광고를 검색하고, 광고 하나를 열어 라이브러리가 공개하는 광고비를 낸 주체, 노출 수, 도달한 국가를 받습니다.

LinkedIn 광고 라이브러리를 비동기 task API로 읽어 경쟁사가 전문가를 대상으로 어떤 광고를 하는지 JSON으로 받습니다. ADS는 자기 엔진입니다. `taskType` `ADS`에 `platform` `linkedin_ad_library`를 보내고, `action`으로 읽을 대상을 고릅니다. 광고 라이브러리 중에서 고르려면 [광고 라이브러리 비교](https://docs.querying.ai/ko/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}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](https://docs.querying.ai/ko/concepts/async-tasks.md). 라이브러리가 읽는 속도를 제한하므로 광고 120개 검색은 약 30초가 걸립니다.

## 경쟁사 광고 분석

요청 세 개로 경쟁사 분석을 마칩니다.

1. 경쟁사 이름을 `advertiserName`에 넣어 `search`를 보내 광고를 나열합니다. `advertiserName`은 이름의 일부와 맞으므로 광고마다 `advertiserName`을 확인합니다. `query`를 더해 광고를 한 주제로 좁히고, `sortBy` `oldest`로 가장 오래된 광고부터 봅니다.
2. 광고의 `libraryId`로 `ad`를 보내 광고비를 낸 주체, 랜딩 페이지를 받고, EU에 노출된 광고는 게재 기간, 노출 수, 타기팅도 받습니다.
3. `payer`로 `search`를 보내 에이전시나 회사가 어느 페이지에서 내든 비용을 낸 광고를 나열합니다.

## 입력

* `action`: `search`(기본값), `ad`.
* `query`: 광고 문구의 키워드. `search`에는 `query`, `advertiserName`, `payer` 중 하나가 필요합니다.
* `advertiserName`: 이름. 광고주 이름의 일부와 맞춥니다(예: `samsung`).
* `payer`: 광고비를 낸 주체의 이름. 이름의 일부와 맞춥니다(예: `Starcom`).
* `libraryId`: 광고의 숫자 ID(예: `1638962914`). `ad`에 필수입니다.
* `country`: 광고가 게재된 국가의 2글자 코드, 또는 모든 국가를 뜻하는 `ALL`(기본값).
* `startDate`, `endDate`: `YYYY-MM-DD`. 함께 보내며 최근 1년 안이어야 합니다. 두 날짜 사이에 노출된 광고를 남깁니다.
* `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`로 완료됩니다.

## 라이브러리가 보관하는 범위

* 모든 광고의 소재, 광고주, 광고비를 낸 주체를 모든 국가에서 받을 수 있습니다.
* 게재 기간, 노출 수 범위, 국가별 노출 비중, 타기팅은 EU에 노출된 광고에서만 받을 수 있습니다.
* 라이브러리는 광고를 약 12개월간 보관하며, 날짜 필터는 최근 1년만 받습니다.

## 광고 하나 열기

`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`)를 나열합니다. EU에 노출되지 않은 광고(예: Adobe 광고 `1698237666`)는 날짜, `impressions`, `targeting`, `reachedCountries`가 `null`입니다. 광고비를 낸 주체와 광고주는 모든 광고에 있습니다.
* `videos`는 동영상마다 `url`(비트레이트가 가장 높은 파일), `files`(모든 mp4: `url`, `type`, `bitrate`), `previewUrl`을 나열합니다. 캐러셀 광고는 `cards`(`title`, `imageUrl`)를, 문서 광고는 `document`(제목, 페이지 수, 페이지 표지)를 더합니다.
* `advertiser`는 광고 뒤의 페이지입니다. `advertiserId`, `advertiserName`, `url`, `type`, `logoUrl`이 있습니다.
* EU에 노출되지 않은 광고의 `transparency`는 `null`입니다. EU에 노출된 광고는 `impressions`, `impressionsText`(`50k-100k`처럼 라이브러리가 주는 텍스트), `reachByCountry`를 담습니다. 이 값은 EU 밖을 포함해 국가별 노출 비중(`country`, `countryCode`, `share`, `shareText`)입니다.
* `variants`는 라이브러리가 두 개 이상 보여 줄 때 광고의 다른 버전을 나열하고, 그렇지 않으면 `null`입니다.
* 소재의 미디어 URL은 수년간 열려 있습니다. 캐러셀 카드의 URL은 약 1주일 뒤, 광고주 로고는 약 2주 반 뒤 만료됩니다. 필요한 파일은 따로 저장합니다.
* 라이브러리에 광고가 없는 `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/ko/engines/ad-libraries.md)
* [Meta 광고 라이브러리](https://docs.querying.ai/ko/engines/meta-ad-library.md)
* [엔진 목록](https://docs.querying.ai/ko/engines/overview.md)
* [크레딧과 한도](https://docs.querying.ai/ko/concepts/credits-and-limits.md)


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