> ## 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 do TikTok Ads

> Analise os anúncios dos concorrentes no TikTok em JSON: pesquise na Biblioteca de Anúncios do TikTok os anúncios que um anunciante veicula na Europa, no Reino Unido, na Suíça, na Türkiye e no Brasil com impressões e segmentação, e leia o Creative Center para ver os anúncios de melhor desempenho de um país.

Leia as fontes de anúncios do TikTok como JSON pela API de tarefas assíncronas. ADS é um mecanismo próprio: envie `taskType` `ADS` com uma de duas plataformas, 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).

* `tiktok_ad_library` lê a Biblioteca de Anúncios do TikTok (a Commercial Content Library). Ela lista os anúncios exibidos em 34 regiões: os países da UE e do EEE, o Reino Unido, a Suíça, a Türkiye e o Brasil. Cada anúncio traz o primeiro e o último dia de exibição e uma faixa de impressões, e `ad` acrescenta a página de destino, quem pagou, a segmentação e as impressões por país, idade e gênero. Use-a para ver todos os anúncios de um concorrente.
* `tiktok_creative_center` lê os principais anúncios do TikTok Creative Center. Ele lista os anúncios que tiveram o melhor desempenho em um país nos últimos 7, 30 ou 180 dias, com taxa de cliques, curtidas e setor, para 28 países, incluindo EUA, Coreia e Japão. Use-o para ver quais criativos funcionam em um mercado.

Uma busca custa **0.5 crédito a cada 30 anúncios** que retorna nas duas plataformas. `advertisers` e `ad` custam 0.5 crédito cada.

## Biblioteca de Anúncios do TikTok

### 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": "tiktok_ad_library", "advertiserName": "NIKE Retail B.V.", "country": "DE", "sortBy": "published_asc", "limit": 14 } }'
```

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). Uma busca de 300 anúncios leva cerca de um minuto.

### Analise os anúncios de um concorrente

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

1. `advertisers` com o início do nome do concorrente retorna os nomes exatos e os IDs que a biblioteca conhece.
2. `search` com esse nome em `advertiserName` lista os anúncios do anunciante. `sortBy` os ordena por data de publicação, data da última exibição ou impressões, `activeStatus` mantém os anúncios ativos ou os que pararam, e `summary` conta os formatos e os anúncios que começaram em cada semana.
3. `ad` com o `libraryId` de um anúncio retorna a página de destino, quem pagou, a segmentação, o tamanho do público e as impressões por país, idade e gênero.

Para encontrar anúncios pelo que eles dizem, use `query` em vez de `advertiserName`: ele pesquisa o texto, as hashtags e os nomes dos anunciantes.

### Parâmetros

* `action`: `search` (padrão), `advertisers` ou `ad`.
* `country`: Obrigatório em todas as ações. Um de `AT`, `BE`, `BG`, `BR`, `CH`, `CY`, `CZ`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GB`, `GR`, `HR`, `HU`, `IE`, `IS`, `IT`, `LI`, `LT`, `LU`, `LV`, `MT`, `NL`, `NO`, `PL`, `PT`, `RO`, `SE`, `SI`, `SK` e `TR`. `ALL` e países fora da lista, como `US`, `KR` e `JP`, são recusados com `400 VALIDATION_ERROR`, porque a biblioteca cobre apenas essas regiões.
* `query`: Uma palavra-chave. Em `search`, corresponde ao texto, às hashtags e aos anunciantes por ordem de relevância, e a biblioteca conta no máximo 5,000 anúncios. Em `advertisers`, é o início do nome de um anunciante e é obrigatório. `search` precisa de `query` ou `advertiserName`, e não de ambos.
* `advertiserName`: O nome exato de um anunciante, como `NIKE Retail B.V.`. A biblioteca conta todos os anúncios dele.
* `libraryId`: O ID numérico de um anúncio, como `1879578148398450`. `ad` o exige.
* `activeStatus`: `all` (padrão), `active` ou `inactive`.
* `mediaType`: `all` (padrão), `video` ou `image`.
* `startDate`, `endDate`: `YYYY-MM-DD`. Mantém os anúncios exibidos entre os dois dias. O padrão são os últimos 365 dias.
* `sortBy`: `published_desc` (padrão), `published_asc`, `last_shown_desc`, `last_shown_asc`, `impressions_desc` ou `impressions_asc`. Vale para uma busca por `advertiserName`, e uma busca por `query` segue sempre a ordem de relevância.
* `limit`: De 1 a 300 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`. `advertisers` lê `query` e `country`, e `ad` lê `libraryId` e `country`. 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`, `country`, `activeStatus`, `mediaType`, intervalo de datas ou `sortBy` diferente é recusado com `400 VALIDATION_ERROR`, enquanto `limit` pode mudar. Em uma busca por `query`, que a biblioteca ordena por relevância, alguns anúncios no limite entre duas páginas podem se repetir ou ficar de fora; `libraryId` permite identificar as repetições.

### Encontre um anunciante

`action` `advertisers` retorna até 20 anunciantes cujos nomes começam com `query`. Envie o nome exato como `advertiserName` para buscar os anúncios desse anunciante.

```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": "tiktok_ad_library", "action": "advertisers", "query": "nike", "country": "DE" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "advertisers",
  "country": "DE",
  "query": "nike",
  "returnedCount": 5,
  "advertisers": [
    {
      "advertiserId": "7587573238117498896",
      "advertiserName": "NIKE COM SRL",
      "country": null,
      "verified": null,
      "adCount": null
    }
  ]
}
```

Cada anunciante tem `advertiserId` e `advertiserName`. `country`, `adCount` e `verified` são `null`, porque as sugestões da biblioteca não informam mais. Uma busca de anunciantes custa 0.5 crédito.

### Resposta da busca

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "search",
  "country": "DE",
  "advertiserName": "NIKE Retail B.V.",
  "activeStatus": "all",
  "mediaType": "all",
  "sortBy": "published_asc",
  "totalCount": 20862,
  "returnedCount": 14,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiRDBZOVVUcnFNamhOQkhXVyIsImMiOiJleUpzWVhOMFgzTnZjblFpT2xzeE56WXdOakF5TVRnM01EQXdYU3dpYm1WNGRGOWpkWEp6YjNJaU9qRXlmUT09IiwicyI6MiwicCI6MTR9",
  "libraryUrl": "https://library.tiktok.com/ads?region=DE&start_time=1763856000000&end_time=1795391999000&adv_name=NIKE%20Retail%20B.V.&adv_biz_ids=&query_type=2&sort_type=create_time%2Casc&ad_type=0&ad_status=0",
  "ads": [
    {
      "position": 1,
      "libraryId": "1845598948737025",
      "libraryUrl": "https://library.tiktok.com/ads/detail/",
      "advertiserId": null,
      "advertiserName": "NIKE Retail B.V.",
      "isActive": null,
      "startDate": "2025-10-22",
      "endDate": "2025-12-21",
      "activeDays": 61,
      "platforms": ["TIKTOK"],
      "format": "VIDEO",
      "title": "Built to Move Different.",
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": { "min": 400000, "max": 500000 },
      "estimatedAudience": "400K-500K",
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUghNK4doIQWDyBoVB8FvvvEQmDDPMAupgfSf8~tplv-tiktokx-origin.jpeg"
      ],
      "videos": [
        {
          "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUghNK4doIQWDyBoVB8FvvvEQmDDPMAupgfSf8~tplv-tiktokx-origin.jpeg",
          "url": "https://library.tiktok.com/api/v1/cdn/1795365691/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTAwNTFjMDAxLXNnL29rbWhwZ2c4ZkFReU52UHJnRE5vOGZCNFZFQlFGRHZ1UEtHSWlvLw==/3cddf31b-4bd3-44fc-b813-42e1897d9536"
        }
      ],
      "category": null,
      "objective": null
    }
  ],
  "summary": {
    "ads": 14,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "NIKE Retail B.V.", "ads": 14 }
    ],
    "formats": { "IMAGE": 2, "VIDEO": 12 },
    "platforms": { "TIKTOK": 14 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [
      { "week": "2025-W42", "ads": 4 }
    ],
    "longestRunning": [
      {
        "libraryId": "1845598948737025",
        "advertiserName": "NIKE Retail B.V.",
        "isActive": null,
        "activeDays": 61,
        "title": "Built to Move Different."
      }
    ],
    "oldestStartDate": "2025-10-16",
    "newestStartDate": "2025-11-11",
    "medianActiveDays": 61
  }
}
```

* A resposta repete `platform`, `action`, `country`, `query` ou `advertiserName`, `activeStatus`, `mediaType` e `sortBy`. `totalCount` é a contagem da biblioteca dos anúncios correspondentes, que para em 5,000 em uma busca por `query`. `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.
* Cada anúncio tem `position`, `libraryId`, `libraryUrl`, `advertiserName`, `title`, `format` (`VIDEO`, `IMAGE` ou `TEXT`), `images`, `videos` (`url`, `previewUrl`), `startDate`, `endDate`, `activeDays`, `impressions` (`min`, `max`), `estimatedAudience` (a faixa da biblioteca, como `400K-500K`) e `platforms` (`TIKTOK`).
* `startDate` e `endDate` são o primeiro e o último dia em que a biblioteca mostra o anúncio (dias em UTC). `activeDays` conta os dias de `startDate` a `endDate`, ambos incluídos. A biblioteca não informa o gasto.
* `isActive` é `true` ou `false` quando `activeStatus` é `active` ou `inactive`, e `null` quando é `all`.
* `advertiserId`, `payer`, `linkUrl`, `landingDomain`, `utm` e `targeting` são `null` em uma busca. `ad` os preenche.
* `summary` conta os anúncios desta resposta: `ads`, `activeAds`, `advertisers` (os 10 com mais anúncios), `formats`, `platforms`, `oldestStartDate`, `newestStartDate` e `medianActiveDays`, com `launchesByWeek` (os anúncios que começaram em cada semana ISO) e `longestRunning` (os 5 anúncios com mais `activeDays`). Não tem `landingDomains` nem `utmCampaigns`, porque uma busca não traz páginas de destino.
* As URLs de imagens e vídeos são assinadas e expiram cerca de 5 a 6 horas após a leitura. Salve os arquivos de que precisar.
* Uma busca sem anúncios correspondentes termina com `ads` vazio e um `summary` de `0` anúncios.

### O que a biblioteca guarda

A biblioteca mostra os anúncios exibidos em suas 34 regiões e os guarda por cerca de 13 meses. Ela informa o primeiro e o último dia de exibição e uma faixa de impressões de cada anúncio. Não publica o gasto.

### Abra um anúncio

`action` `ad` abre o anúncio com o `libraryId` e o `country` que você enviar.

```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": "tiktok_ad_library", "action": "ad", "libraryId": "1879578148398450", "country": "DE" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "ad",
  "country": "DE",
  "libraryId": "1879578148398450",
  "ad": {
    "position": 1,
    "libraryId": "1879578148398450",
    "libraryUrl": "https://library.tiktok.com/ads/detail/",
    "advertiserId": "6876453864464188162",
    "advertiserName": "NIKE Retail B.V.",
    "isActive": null,
    "startDate": "2026-10-20",
    "endDate": "2026-11-08",
    "activeDays": 20,
    "platforms": ["TIKTOK"],
    "format": "VIDEO",
    "title": "Neue Winterausrüstung in Nike Factory Stores.",
    "body": null,
    "ctaText": "Learn more",
    "ctaType": null,
    "linkUrl": "https://www.nike.com/de/retail",
    "landingDomain": "nike.com",
    "utm": null,
    "payer": "INITIATIVE MEDIA B.V.",
    "impressions": { "min": 300000, "max": 400000 },
    "estimatedAudience": "300K-400K",
    "targeting": {
      "byCountry": [
        { "country": "DE", "ages": ["18-24"], "genders": ["FEMALE"] }
      ],
      "cities": [],
      "creatorInteractions": null,
      "customAudience": "No",
      "deviceModels": [],
      "excludesAudience": "No",
      "highSpendingPower": "No",
      "interests": null,
      "languages": [],
      "operatingSystems": ["ALL"],
      "provinces": ["Berlin"],
      "targetAudienceSize": "15.5M-18.9M",
      "videoInteractions": null
    },
    "reachedCountries": ["DE"],
    "images": [
      "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261013c7c72a61615657cc4f6482cd~tplv-tiktokx-origin.jpeg"
    ],
    "videos": [
      {
        "previewUrl": "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261013c7c72a61615657cc4f6482cd~tplv-tiktokx-origin.jpeg",
        "url": "https://library.tiktok.com/api/v1/cdn/1795365698/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTUxYzc5OS1zZy9vc21jZFFBbjhBZ1BlRWVWQU1iVmRVQ2tzUUQ0WEdrUlVMRVJoZi8=/9aa37923-f585-4393-b635-1409c7ce6656"
      }
    ],
    "category": "Apparel & Accessories",
    "objective": "Traffic"
  },
  "advertiser": {
    "advertiserId": "6876453864464188162",
    "advertiserName": "NIKE Retail B.V.",
    "payer": "INITIATIVE MEDIA B.V.",
    "account": {
      "verified": true,
      "accountType": "VERIFIED_BA",
      "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e0b0ac7b6ad6447a8e923fd1eb162f2c~tplv-tiktokx-cropcenter:168:168.jpeg",
      "displayName": "Nike",
      "followers": "9.4M",
      "profileUrl": "https://www.tiktok.com/share/user/208464585232822272",
      "username": "nike"
    },
    "registryCountry": "Netherlands"
  },
  "transparency": {
    "byCountry": [
      {
        "country": "DE",
        "impressions": "357K",
        "breakdowns": [
          { "impressions": "44K", "age": "18-24", "gender": "MALE" }
        ]
      }
    ],
    "totalImpressions": "300K-400K"
  }
}
```

* `ad` tem os campos de um anúncio de busca, mais `linkUrl`, `landingDomain`, `payer` (quem pagou o anúncio), `category`, `objective`, `ctaText`, `advertiserId`, `reachedCountries` e `targeting`.
* `targeting` traz `byCountry` (os `ages` e `genders` de cada país), `provinces`, `cities`, `languages`, `interests`, `targetAudienceSize` (a faixa da biblioteca, como `15.5M-18.9M`), `customAudience`, `excludesAudience`, `highSpendingPower`, `operatingSystems`, `deviceModels`, `videoInteractions` e `creatorInteractions`. Uma parte que a biblioteca não publica para o anúncio é `null` ou vazia.
* `advertiser` tem `advertiserId`, `advertiserName`, `payer`, `registryCountry` e a `account` do TikTok por trás dos anúncios (`username`, `displayName`, `verified`, `followers`, `accountType`, `profileUrl`, `avatarUrl`).
* `transparency` traz `totalImpressions` e `byCountry`: as `impressions` de cada país e seus `breakdowns` por `age` e `gender`.
* Um `libraryId` para o qual a biblioteca não tem anúncio falha com `PAGE_UNAVAILABLE`.

## TikTok Creative Center

O Creative Center lista os anúncios de melhor desempenho de um país, os anúncios que o TikTok seleciona para os últimos 7, 30 ou 180 dias. É uma amostra ranqueada, e não o conjunto completo de anúncios de um anunciante: o nome do anunciante costuma estar vazio, e a biblioteca não informa datas, gasto nem impressões. Ela informa a taxa de cliques, as curtidas, o nível de custo, o setor e os objetivos de cada anúncio. Use-o para descobrir quais ganchos, formatos e produtos funcionam em um mercado.

### 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": "tiktok_creative_center", "country": "US", "limit": 25 } }'
```

### Parâmetros

* `action`: `search` (padrão) ou `ad`. `advertisers` é recusado com `400 VALIDATION_ERROR`, porque o Creative Center não tem busca de anunciantes.
* `country`: Obrigatório em `search`. Um de `AE`, `AR`, `AU`, `BR`, `CA`, `CO`, `DE`, `ES`, `FR`, `GB`, `ID`, `IT`, `JP`, `KR`, `MX`, `MY`, `NL`, `PH`, `PK`, `RO`, `SA`, `SE`, `SG`, `TH`, `TR`, `US`, `VN` e `ZA`. `ALL` é recusado.
* `query`: Uma palavra-chave.
* `period`: `7`, `30` (padrão) ou `180` dias.
* `industry`: Um ID de setor, como `21103000000` (Hardware & Electrical), como o `industry.id` de um anúncio o nomeia.
* `objective`: `traffic`, `app_installs`, `conversions`, `video_views`, `reach`, `lead_generation`, `product_sales` ou `app_promotion`.
* `adLanguage`: Um código de idioma: `en`, `es`, `ar`, `vi`, `th`, `de`, `id`, `pt`, `fr`, `ms`, `nl`, `ja`, `it`, `ro`, `zh-Hant` ou `ko`.
* `adFormat`: `spark` (anúncios que impulsionam a publicação de um criador) ou `non_spark`.
* `sortBy`: `for_you` (padrão), `impression`, `ctr`, `play_2s_rate`, `play_6s_rate`, `cvr` ou `like`.
* `limit`: De 1 a 200 anúncios. Padrão 30.
* `cursor`: O `nextCursor` de uma resposta anterior.
* `libraryId`: O ID numérico de um anúncio do ranking. `ad` o exige.

`search` lê todos os campos acima, exceto `libraryId`, e `ad` lê somente `libraryId`. O Creative Center lista no máximo cerca de 400 a 500 anúncios para um país, um período e um conjunto de filtros (`totalCount`).

### Resposta da busca

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_creative_center",
  "action": "search",
  "country": "US",
  "period": 30,
  "sortBy": "for_you",
  "totalCount": 183,
  "returnedCount": 25,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiUzJCUk5GZ2V4bkNsM1NXcyIsImciOjIsInMiOjYsInAiOjI1fQ",
  "libraryUrl": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en",
  "ads": [
    {
      "position": 1,
      "libraryId": "7705106910069080084",
      "libraryUrl": null,
      "advertiserId": null,
      "advertiserName": null,
      "isActive": null,
      "startDate": null,
      "endDate": null,
      "activeDays": null,
      "platforms": ["TIKTOK"],
      "format": "VIDEO",
      "width": 720,
      "height": 1280,
      "title": "No-BS Tool Video 103: Northern Tool + Equipment Wide Truck Toolbox",
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-51c799-sg/oAQ4uJuVEAkCTi0B2YczHAViMtauDHIKBpPBA~tplv-noop.image"
      ],
      "videos": [
        {
          "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-51c799-sg/oAQ4uJuVEAkCTi0B2YczHAViMtauDHIKBpPBA~tplv-noop.image",
          "url": "https://v16m-default.tiktokcdn.com/dd86ec10034c2f4740daf53e9bd6c280/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/oAMlOqB0IiATEFAdXQioXCBIAywNfmmu18gjwb/"
        }
      ],
      "aiSummary": null,
      "comments": null,
      "costLevel": 0,
      "ctrPercent": 0.66,
      "durationSeconds": 19.834,
      "industry": { "id": "21103000000", "name": "Hardware & Electrical" },
      "keywords": null,
      "likes": 787,
      "objectives": ["video_views"],
      "shares": null,
      "source": null,
      "videoUrls": {
        "1080p": "https://v16m-default.tiktokcdn.com/dd86ec10034c2f4740daf53e9bd6c280/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/oAMlOqB0IiATEFAdXQioXCBIAywNfmmu18gjwb/",
        "360p": "https://v16m-default.tiktokcdn.com/b36269b95476575962b9c114fc501dc3/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/o0NvZBpNAk4I2gfqugQFEnK7QB5fuCkcAgDEDZ/",
        "480p": "https://v16m-default.tiktokcdn.com/59590e737aed92b6a688cb20125bb307/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/ogfcNqEZ7n5EDE34BAIB2knfpNgg7FQDgKQBug/",
        "540p": "https://v16m-default.tiktokcdn.com/16951456d88cf46000321fb9be66eaa0/6b036fbb/video/tos/alisg/tos-alisg-ve-51c799-sg/oUfDB7pQBIAg2F65KQEncfgougEkZBDvqQNNpF/",
        "720p": "https://v16m-default.tiktokcdn.com/7be67d46e9a7a041e395d2bfabd195f2/6b036fbb/video/tos/alisg/tos-alisg-ve-51c799-sg/osfGceBcVAqbGTPRAaIIATCgED3LgJryVtPzNf/"
      },
      "voiceOver": null
    }
  ],
  "summary": {
    "ads": 25,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "Marco Seven", "ads": 1 }
    ],
    "formats": { "VIDEO": 25 },
    "platforms": { "TIKTOK": 25 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [],
    "longestRunning": [],
    "oldestStartDate": null,
    "newestStartDate": null,
    "medianActiveDays": null
  }
}
```

* A resposta repete `platform`, `action`, `country`, `period`, `sortBy` e os filtros recebidos. `totalCount` é o número de anúncios do ranking para essa combinação.
* Cada anúncio tem `position`, `libraryId`, `title`, `advertiserName` (muitas vezes `null`), `format`, `ctrPercent` (a taxa de cliques em porcentagem), `costLevel`, `likes`, `industry` (`id`, `name`), `objectives`, `durationSeconds`, `width`, `height`, `voiceOver`, `images`, `videos` e `videoUrls` (o arquivo de vídeo por resolução, como `360p` e `1080p`).
* O Creative Center não informa `startDate`, `endDate`, `impressions` nem `libraryUrl`, então esses campos são `null`, e `summary` conta apenas os formatos, os anunciantes e as plataformas.
* As URLs de vídeo e imagem são assinadas e expiram cerca de 5 a 6 horas após a leitura.

### Abra um anúncio

`action` `ad` abre um anúncio do ranking por `libraryId` e acrescenta `linkUrl`, `landingDomain`, `reachedCountries`, `comments`, `shares` e `source` (onde o anúncio foi criado, como `TikTok Ads Manager`).

```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": "tiktok_creative_center", "action": "ad", "libraryId": "7699613362636095496" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_creative_center",
  "action": "ad",
  "libraryId": "7699613362636095496",
  "ad": {
    "position": 1,
    "libraryId": "7699613362636095496",
    "libraryUrl": null,
    "advertiserId": null,
    "advertiserName": "Bob Mills Furniture",
    "isActive": null,
    "startDate": null,
    "endDate": null,
    "activeDays": null,
    "platforms": ["TIKTOK"],
    "format": "VIDEO",
    "width": 720,
    "height": 1280,
    "title": "Better Sleep Starts with the Right Mattress",
    "body": null,
    "ctaText": null,
    "ctaType": null,
    "linkUrl": "https://www.bobmillsfurniture.com/sleep-experts",
    "landingDomain": "bobmillsfurniture.com",
    "utm": null,
    "payer": null,
    "impressions": null,
    "targeting": null,
    "reachedCountries": ["US"],
    "images": [
      "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o47taaAAR0LVnI7BhqzPAuKziAYczLByGJi4E~tplv-noop.image"
    ],
    "videos": [
      {
        "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o47taaAAR0LVnI7BhqzPAuKziAYczLByGJi4E~tplv-noop.image",
        "url": "https://v16m-default.tiktokcdn.com/474b4bf87f62a54743f28d85725bcaf2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oE9AQRij1FVAIezCN8Q3CWtGbD2MUAsgqg8e3f/"
      }
    ],
    "aiSummary": null,
    "comments": 0,
    "costLevel": 1,
    "ctrPercent": 0.2,
    "durationSeconds": 30.55,
    "industry": { "id": "23123000000", "name": "Sports & Fitness" },
    "keywords": null,
    "likes": 28,
    "objectives": ["traffic"],
    "shares": 0,
    "source": "TikTok Ads Manager",
    "videoUrls": {
      "1080p": "https://v16m-default.tiktokcdn.com/474b4bf87f62a54743f28d85725bcaf2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oE9AQRij1FVAIezCN8Q3CWtGbD2MUAsgqg8e3f/",
      "360p": "https://v16m-default.tiktokcdn.com/93487026a84b0472c46d3ff9471ee8f7/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oo1kCLCbgGVGt1GsCACGAAzbQefjqmDIfyIXQg/",
      "480p": "https://v16m-default.tiktokcdn.com/49d6ee93d4fc380675d41954037c55d1/6b036fca/video/tos/alisg/tos-alisg-ve-51c799-sg/okfRtfZroqDRIgEzhatFVDwDBABy2ENaWhQAQB/",
      "540p": "https://v16m-default.tiktokcdn.com/ce0699fb34b5ba3ccaa5251fba131ce2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUCWfxEEIBgqR32fDhFQapDtyZWaEDAVDBoNQh/",
      "720p": "https://v16m-default.tiktokcdn.com/d27a8eba19586eacc4784887cdd649e3/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/o0fNIDWVyhREjDDafOB4EzahgQFZBqAo2tDQhE/"
    },
    "voiceOver": false
  }
}
```

Um `libraryId` para o qual o Creative Center 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` 300 na Biblioteca de Anúncios reserva 5 créditos. `advertisers` e `ad` custam 0.5 crédito cada. 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.