> ## 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.

# API da Biblioteca de Anúncios do LinkedIn

> Analise os anúncios dos concorrentes na Biblioteca de Anúncios do LinkedIn em JSON: pesquise os anúncios por palavra-chave, anunciante ou pagador, e abra um anúncio para ver quem pagou, as impressões e os países que ele alcançou, quando a biblioteca os publica.

Leia a Biblioteca de Anúncios do LinkedIn como JSON pela API de tarefas assíncronas para ver o que seus concorrentes anunciam para profissionais. ADS é um mecanismo próprio: envie `taskType` `ADS` com `platform` `linkedin_ad_library`, e `action` escolhe o que ler. Para escolher entre as bibliotecas de anúncios, veja [Bibliotecas de anúncios comparadas](https://docs.querying.ai/pt/engines/ad-libraries.md).

* `search` (padrão) lista anúncios por uma palavra-chave em `query`, pelo nome de um anunciante em `advertiserName`, por quem pagou em `payer`, ou por uma combinação. Cada anúncio traz o anunciante, o formato, o título, o texto e a mídia, e a resposta termina com um `summary` dos anúncios retornados.
* `ad` abre um anúncio: o anunciante, quem pagou, a página de destino e, onde a biblioteca os publica, as datas de veiculação, as impressões, os países que ele alcançou e a segmentação.

A biblioteca não tem busca de anunciantes, então `action` `advertisers` é recusada com `400 VALIDATION_ERROR`. Encontre um concorrente com `advertiserName` em uma busca.

Uma busca custa **0.5 crédito a cada 30 anúncios** que retorna. `ad` custa 0.5 crédito.

## Requisição

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

Envie a tarefa e depois consulte `GET /v1/async/task/{id}` ou receba o webhook. Veja [Tarefas assíncronas](https://docs.querying.ai/pt/concepts/async-tasks.md). A biblioteca limita a velocidade de leitura, então uma busca de 120 anúncios leva cerca de meio minuto.

## Analise os anúncios de um concorrente

Três requisições cobrem uma análise de concorrentes:

1. `search` com o nome do concorrente em `advertiserName` lista os anúncios dele. `advertiserName` corresponde a parte de um nome, então confira `advertiserName` em cada anúncio. Adicione `query` para restringir os anúncios a um tema, e `sortBy` `oldest` para começar pelos anúncios mais antigos.
2. `ad` com o `libraryId` de um anúncio retorna quem pagou, a página de destino e, nos anúncios exibidos na UE, as datas de veiculação, as impressões e a segmentação.
3. `search` com `payer` lista os anúncios que uma agência ou empresa pagou, seja qual for a página que os veicula.

## Parâmetros

* `action`: `search` (padrão) ou `ad`.
* `query`: Uma palavra-chave no texto do anúncio. `search` precisa de `query`, `advertiserName` ou `payer`.
* `advertiserName`: Um nome, comparado como parte do nome do anunciante, como `samsung`.
* `payer`: O nome de quem pagou o anúncio, comparado como parte do nome, como `Starcom`.
* `libraryId`: O ID numérico de um anúncio, como `1638962914`. `ad` o exige.
* `country`: Onde os anúncios foram exibidos, como código de país de duas letras, ou `ALL` para todos os países (padrão).
* `startDate`, `endDate`: `YYYY-MM-DD`, enviados juntos, dentro do último ano. Mantém os anúncios exibidos entre os dois dias.
* `sortBy`: `newest` (padrão) ou `oldest`.
* `limit`: De 1 a 120 anúncios. Padrão 30.
* `cursor`: O `nextCursor` de uma resposta anterior, para ler os anúncios seguintes.

`search` lê todos os campos acima, exceto `libraryId`, e `ad` lê somente `libraryId`. Um filtro da Biblioteca de Anúncios da Meta (`pageId`, `pageIds`, `activeStatus`, `searchType`, `adType`, `mediaType`, `publisherPlatforms` ou `contentLanguages`), um valor que a biblioteca não consegue pesquisar ou um campo que a ação não lê é recusado com `400 VALIDATION_ERROR`, e `details` indica o campo.

## Ler mais anúncios

Uma resposta com mais anúncios para ler traz `nextCursor`. Envie-o como `cursor` com a mesma busca para receber os anúncios seguintes, de novo até `limit`. `nextCursor` é `null` quando a biblioteca não tem mais. Um cursor só funciona com a busca que o retornou: um `query`, `advertiserName`, `payer`, `country`, intervalo de datas ou `sortBy` diferente é recusado com `400 VALIDATION_ERROR`, enquanto `limit` pode mudar.

## Resposta da busca

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

* A resposta repete `platform`, `action`, `country`, `query`, `advertiserName`, `payer`, `sortBy` e as datas recebidas. `returnedCount` conta os anúncios em `ads`, `hasMore` é `true` quando a biblioteca tem mais, o que `nextCursor` lê, e `libraryUrl` abre a mesma busca na Biblioteca de Anúncios. `totalCount` é `null`, porque a biblioteca não informa uma contagem.
* Cada anúncio é um card: `position`, `libraryId`, `libraryUrl`, `advertiserName`, `advertiserLogoUrl`, `creativeType` (como `SPONSORED_STATUS_UPDATE` ou `SPONSORED_VIDEO`), `format`, `title`, `body`, `images` e `videos` (o pôster do vídeo em `previewUrl`), e `platforms` (`LINKEDIN`). `format` é `IMAGE`, `VIDEO`, `CAROUSEL`, `DOCUMENT`, `ARTICLE`, `MESSAGE`, `JOB`, `SPOTLIGHT` ou `FOLLOW_COMPANY`.
* Anúncios de mensagem e anúncios Thought Leader trazem `member`, o remetente da mensagem ou o membro cuja publicação o anúncio promove, com `name` e `url`; `ad` o retorna no mesmo formato. Nos demais anúncios, `member` é `null`.
* Um card traz os primeiros 120 caracteres do texto, e `bodyTruncated` é `true` quando o texto é mais longo. `ad` retorna o texto completo.
* `advertiserId`, `payer`, `startDate`, `endDate`, `activeDays`, `linkUrl`, `landingDomain`, `impressions`, `targeting`, `ctaText` e `utm` são `null` em um card. `ad` os preenche onde a biblioteca os tem. `isActive` é `null`, porque a biblioteca não informa se um anúncio ainda roda.
* `summary` conta os anúncios desta resposta: `ads`, `advertisers` (os 10 com mais anúncios: `advertiserName`, `ads`), `formats` e `platforms`. Os campos de data dele (`oldestStartDate`, `newestStartDate`, `medianActiveDays`, `launchesByWeek` e `longestRunning`) ficam vazios ou `null`, porque os cards não trazem datas.
* Uma busca sem anúncios correspondentes termina com `ads` vazio e um `summary` de `0` anúncios.

## O que a biblioteca guarda

* O criativo, o anunciante e o pagador de cada anúncio estão disponíveis para todos os países.
* As datas de veiculação, a faixa de impressões, a participação das impressões por país e a segmentação estão disponíveis apenas para anúncios exibidos na UE.
* A biblioteca guarda os anúncios por cerca de 12 meses, e o filtro de datas aceita apenas o último ano.

## Abra um anúncio

`action` `ad` abre o anúncio com o `libraryId` que você enviar, obtido em uma busca ou no endereço da Biblioteca de Anúncios `/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` tem os campos de um card de busca com o texto completo, mais `advertiserId`, `advertiserUrl`, `advertiserType` (`company` ou `person`), `payer` (quem pagou o anúncio), `linkUrl`, `landingDomain`, `ctaText`, `startDate`, `endDate`, `activeDays`, `impressions`, `targeting` e `reachedCountries`.
* `impressions` é a faixa que a biblioteca publica (`min`, `max`). `targeting` lista os idiomas e locais que o anunciante incluiu ou excluiu (`language`, `location`) e os parâmetros de segmentação (`parameters`: `parameter`, `targeted`, `excluded`). As datas, `impressions`, `targeting` e `reachedCountries` são `null` em um anúncio que não foi exibido na UE, como o anúncio da Adobe `1698237666`. O pagador e o anunciante aparecem em todos os anúncios.
* `videos` lista cada vídeo com `url` (o arquivo com o maior bitrate), `files` (cada mp4: `url`, `type`, `bitrate`) e `previewUrl`. Um anúncio em carrossel acrescenta `cards` (`title`, `imageUrl`) e um anúncio de documento acrescenta `document` (o título, o número de páginas e as capas das páginas).
* `advertiser` é a página por trás do anúncio: `advertiserId`, `advertiserName`, `url`, `type` e `logoUrl`.
* `transparency` é `null` em um anúncio não exibido na UE. Em um anúncio exibido na UE, contém `impressions`, `impressionsText` (o texto da biblioteca, como `50k-100k`) e `reachByCountry`, a participação das impressões em cada país (`country`, `countryCode`, `share`, `shareText`), inclusive fora da UE.
* `variants` lista as outras versões do anúncio quando a biblioteca mostra mais de uma, e é `null` nos demais casos.
* As URLs de mídia dos criativos continuam abertas por anos. As URLs dos cards de um carrossel expiram após cerca de uma semana, e os logotipos dos anunciantes após cerca de duas semanas e meia. Salve os arquivos de que precisar.
* Um `libraryId` para o qual a biblioteca não tem anúncio falha com `PAGE_UNAVAILABLE`.

## Preço

Uma busca reserva 0.5 crédito a cada 30 anúncios que o `limit` dela pede, e cobra 0.5 crédito a cada 30 anúncios que retorna, no mínimo 0.5 crédito. A busca padrão de 30 anúncios custa 0.5 crédito, e uma busca com `limit` 120 reserva 2 créditos. `ad` custa 0.5 crédito. Apenas requisições concluídas são cobradas.

## Relacionado

* [Bibliotecas de anúncios comparadas](https://docs.querying.ai/pt/engines/ad-libraries.md)
* [Biblioteca de Anúncios da Meta](https://docs.querying.ai/pt/engines/meta-ad-library.md)
* [Visão geral dos motores](https://docs.querying.ai/pt/engines/overview.md)
* [Créditos e limites](https://docs.querying.ai/pt/concepts/credits-and-limits.md)


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