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

> Analiza los anuncios de la competencia en TikTok como JSON: busca en la Biblioteca de anuncios de TikTok los anuncios que publica un anunciante en Europa, el Reino Unido, Suiza, Türkiye y Brasil con impresiones y segmentación, y lee el Creative Center para ver los anuncios con mejor rendimiento de un país.

Lee las fuentes de anuncios de TikTok como JSON a través de la API asíncrona de tareas. ADS es un motor propio: envía `taskType` `ADS` con una de dos plataformas, y `action` elige qué leer. Para elegir entre las bibliotecas de anuncios, consulta [Bibliotecas de anuncios comparadas](https://docs.querying.ai/es/engines/ad-libraries.md).

* `tiktok_ad_library` lee la Biblioteca de anuncios de TikTok (la Commercial Content Library). Lista los anuncios mostrados en 34 regiones: los países de la UE y del EEE, el Reino Unido, Suiza, Türkiye y Brasil. Cada anuncio incluye su primer y su último día de emisión y un rango de impresiones, y `ad` añade la página de destino, quién pagó, la segmentación y las impresiones por país, edad y género. Úsala para ver todos los anuncios de un competidor.
* `tiktok_creative_center` lee los anuncios destacados del TikTok Creative Center. Lista los anuncios que mejor rindieron en un país durante los últimos 7, 30 o 180 días, con su tasa de clics, sus «me gusta» y su sector, para 28 países, entre ellos EE. UU., Corea y Japón. Úsalo para ver qué creativos funcionan en un mercado.

Una búsqueda cuesta **0.5 créditos por cada 30 anuncios** que devuelve en ambas plataformas. `advertisers` y `ad` cuestan 0.5 créditos cada uno.

## Biblioteca de anuncios de TikTok

### Solicitud

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

Envía la tarea y consulta `GET /v1/async/task/{id}` o recibe su webhook. Consulta [Tareas asíncronas](https://docs.querying.ai/es/concepts/async-tasks.md). Una búsqueda de 300 anuncios tarda aproximadamente un minuto.

### Analiza los anuncios de un competidor

Tres solicitudes cubren un análisis de la competencia:

1. `advertisers` con el inicio del nombre del competidor devuelve los nombres exactos y los IDs que conoce la biblioteca.
2. `search` con ese nombre en `advertiserName` lista los anuncios del anunciante. `sortBy` los ordena por fecha de publicación, fecha de la última emisión o impresiones, `activeStatus` conserva los anuncios en emisión o los detenidos, y `summary` cuenta los formatos y los anuncios que empezaron cada semana.
3. `ad` con el `libraryId` de un anuncio devuelve la página de destino, quién pagó, la segmentación, el tamaño del público y las impresiones por país, edad y género.

Para encontrar anuncios por lo que dicen, usa `query` en lugar de `advertiserName`: busca en el texto, los hashtags y los nombres de los anunciantes.

### Parámetros

* `action`: `search` (por defecto), `advertisers` o `ad`.
* `country`: Obligatorio en todas las acciones. Uno 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` y `TR`. `ALL` y los países fuera de la lista, como `US`, `KR` y `JP`, se rechazan con `400 VALIDATION_ERROR`, porque la biblioteca cubre solo estas regiones.
* `query`: Una palabra clave. En `search` coincide con el texto, los hashtags y los anunciantes por orden de relevancia, y la biblioteca cuenta como máximo 5,000 anuncios. En `advertisers` es el inicio del nombre de un anunciante y es obligatorio. `search` necesita `query` o `advertiserName`, y no ambos.
* `advertiserName`: El nombre exacto de un anunciante, como `NIKE Retail B.V.`. La biblioteca cuenta todos sus anuncios.
* `libraryId`: El ID numérico de un anuncio, como `1879578148398450`. `ad` lo requiere.
* `activeStatus`: `all` (por defecto), `active` o `inactive`.
* `mediaType`: `all` (por defecto), `video` o `image`.
* `startDate`, `endDate`: `YYYY-MM-DD`. Conserva los anuncios mostrados entre los dos días. Por defecto son los últimos 365 días.
* `sortBy`: `published_desc` (por defecto), `published_asc`, `last_shown_desc`, `last_shown_asc`, `impressions_desc` o `impressions_asc`. Se aplica a una búsqueda por `advertiserName`, y una búsqueda por `query` siempre va por orden de relevancia.
* `limit`: De 1 a 300 anuncios. Por defecto 30.
* `cursor`: El `nextCursor` de una respuesta anterior, para leer los anuncios siguientes.

`search` lee todos los campos anteriores excepto `libraryId`. `advertisers` lee `query` y `country`, y `ad` lee `libraryId` y `country`. Un valor que la biblioteca no puede buscar o un campo que la acción no lee se rechaza con `400 VALIDATION_ERROR`, y `details` indica el campo.

### Leer más anuncios

Una respuesta con más anuncios por leer incluye `nextCursor`. Envíalo como `cursor` con la misma búsqueda para recibir los anuncios siguientes, de nuevo hasta `limit`. `nextCursor` es `null` cuando la biblioteca no tiene más. Un cursor solo funciona con la búsqueda que lo devolvió: un `query`, `advertiserName`, `country`, `activeStatus`, `mediaType`, rango de fechas o `sortBy` distinto se rechaza con `400 VALIDATION_ERROR`, mientras que `limit` puede cambiar. En una búsqueda por `query`, que la biblioteca ordena por relevancia, unos pocos anuncios en el límite entre dos páginas pueden repetirse o perderse; `libraryId` permite distinguir los repetidos.

### Encontrar un anunciante

`action` `advertisers` devuelve hasta 20 anunciantes cuyos nombres empiezan por `query`. Envía el nombre exacto como `advertiserName` para buscar los anuncios de ese 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 tiene `advertiserId` y `advertiserName`. `country`, `adCount` y `verified` son `null`, porque las sugerencias de la biblioteca no dan más. Una búsqueda de anunciantes cuesta 0.5 créditos.

### Respuesta de búsqueda

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

* La respuesta devuelve `platform`, `action`, `country`, `query` o `advertiserName`, `activeStatus`, `mediaType` y `sortBy`. `totalCount` es el recuento de la biblioteca de los anuncios coincidentes, que se detiene en 5,000 en una búsqueda por `query`. `returnedCount` cuenta los anuncios de `ads`, `hasMore` es `true` cuando la biblioteca tiene más, que `nextCursor` lee, y `libraryUrl` abre la misma búsqueda en la Biblioteca de anuncios.
* Cada anuncio tiene `position`, `libraryId`, `libraryUrl`, `advertiserName`, `title`, `format` (`VIDEO`, `IMAGE` o `TEXT`), `images`, `videos` (`url`, `previewUrl`), `startDate`, `endDate`, `activeDays`, `impressions` (`min`, `max`), `estimatedAudience` (el rango de la biblioteca, como `400K-500K`) y `platforms` (`TIKTOK`).
* `startDate` y `endDate` son el primer y el último día en que la biblioteca muestra el anuncio (días en UTC). `activeDays` cuenta los días desde `startDate` hasta `endDate`, contando ambos. La biblioteca no da el gasto.
* `isActive` es `true` o `false` cuando `activeStatus` es `active` o `inactive`, y `null` cuando es `all`.
* `advertiserId`, `payer`, `linkUrl`, `landingDomain`, `utm` y `targeting` son `null` en una búsqueda. `ad` los rellena.
* `summary` cuenta los anuncios de esta respuesta: `ads`, `activeAds`, `advertisers` (los 10 con más anuncios), `formats`, `platforms`, `oldestStartDate`, `newestStartDate` y `medianActiveDays`, con `launchesByWeek` (los anuncios que empezaron en cada semana ISO) y `longestRunning` (los 5 anuncios con más `activeDays`). No incluye `landingDomains` ni `utmCampaigns`, porque una búsqueda no incluye páginas de destino.
* Las URL de imágenes y vídeos están firmadas y caducan unas 5 a 6 horas después de la lectura. Guarda los archivos que necesites.
* Una búsqueda sin anuncios coincidentes se completa con `ads` vacío y un `summary` de `0` anuncios.

### Qué conserva la biblioteca

La biblioteca muestra los anuncios emitidos en sus 34 regiones y los conserva unos 13 meses. Da el primer y el último día de emisión y un rango de impresiones de cada anuncio. No publica el gasto.

### Abrir un anuncio

`action` `ad` abre el anuncio con el `libraryId` y el `country` que envíes.

```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` tiene los campos de un anuncio de búsqueda, más `linkUrl`, `landingDomain`, `payer` (quién pagó el anuncio), `category`, `objective`, `ctaText`, `advertiserId`, `reachedCountries` y `targeting`.
* `targeting` incluye `byCountry` (los `ages` y `genders` de cada país), `provinces`, `cities`, `languages`, `interests`, `targetAudienceSize` (el rango de la biblioteca, como `15.5M-18.9M`), `customAudience`, `excludesAudience`, `highSpendingPower`, `operatingSystems`, `deviceModels`, `videoInteractions` y `creatorInteractions`. Una parte que la biblioteca no publica para el anuncio es `null` o está vacía.
* `advertiser` tiene `advertiserId`, `advertiserName`, `payer`, `registryCountry` y la `account` de TikTok detrás de los anuncios (`username`, `displayName`, `verified`, `followers`, `accountType`, `profileUrl`, `avatarUrl`).
* `transparency` incluye `totalImpressions` y `byCountry`: las `impressions` de cada país y sus `breakdowns` por `age` y `gender`.
* Un `libraryId` para el que la biblioteca no tiene ningún anuncio falla con `PAGE_UNAVAILABLE`.

## TikTok Creative Center

El Creative Center lista los anuncios con mejor rendimiento de un país, los que TikTok selecciona para los últimos 7, 30 o 180 días. Es una muestra ordenada, no el conjunto completo de anuncios de un anunciante: el nombre del anunciante suele estar vacío, y la biblioteca no da fechas, gasto ni impresiones. Da la tasa de clics, los «me gusta», el nivel de coste, el sector y los objetivos de cada anuncio. Úsalo para encontrar qué ganchos, formatos y productos funcionan en un mercado.

### Solicitud

```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` (por defecto) o `ad`. `advertisers` se rechaza con `400 VALIDATION_ERROR`, porque el Creative Center no tiene búsqueda de anunciantes.
* `country`: Obligatorio en `search`. Uno 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` y `ZA`. `ALL` se rechaza.
* `query`: Una palabra clave.
* `period`: `7`, `30` (por defecto) o `180` días.
* `industry`: Un ID de sector, como `21103000000` (Hardware & Electrical), tal como lo indica el `industry.id` de un anuncio.
* `objective`: `traffic`, `app_installs`, `conversions`, `video_views`, `reach`, `lead_generation`, `product_sales` o `app_promotion`.
* `adLanguage`: Un código de idioma: `en`, `es`, `ar`, `vi`, `th`, `de`, `id`, `pt`, `fr`, `ms`, `nl`, `ja`, `it`, `ro`, `zh-Hant` o `ko`.
* `adFormat`: `spark` (anuncios que impulsan una publicación de un creador) o `non_spark`.
* `sortBy`: `for_you` (por defecto), `impression`, `ctr`, `play_2s_rate`, `play_6s_rate`, `cvr` o `like`.
* `limit`: De 1 a 200 anuncios. Por defecto 30.
* `cursor`: El `nextCursor` de una respuesta anterior.
* `libraryId`: El ID numérico de un anuncio destacado. `ad` lo requiere.

`search` lee todos los campos anteriores excepto `libraryId`, y `ad` lee solo `libraryId`. El Creative Center lista como máximo unos 400 a 500 anuncios para un país, un periodo y un conjunto de filtros (`totalCount`).

### Respuesta de búsqueda

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

* La respuesta devuelve `platform`, `action`, `country`, `period`, `sortBy` y los filtros recibidos. `totalCount` es el número de anuncios destacados de esa combinación.
* Cada anuncio tiene `position`, `libraryId`, `title`, `advertiserName` (a menudo `null`), `format`, `ctrPercent` (la tasa de clics en porcentaje), `costLevel`, `likes`, `industry` (`id`, `name`), `objectives`, `durationSeconds`, `width`, `height`, `voiceOver`, `images`, `videos` y `videoUrls` (el archivo de vídeo por resolución, como `360p` y `1080p`).
* El Creative Center no da `startDate`, `endDate`, `impressions` ni `libraryUrl`, así que son `null`, y `summary` cuenta solo los formatos, los anunciantes y las plataformas.
* Las URL de vídeo e imagen están firmadas y caducan unas 5 a 6 horas después de la lectura.

### Abrir un anuncio

`action` `ad` abre un anuncio destacado por `libraryId` y añade `linkUrl`, `landingDomain`, `reachedCountries`, `comments`, `shares` y `source` (dónde se creó el anuncio, 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
  }
}
```

Un `libraryId` para el que el Creative Center no tiene ningún anuncio falla con `PAGE_UNAVAILABLE`.

## Precio

Una búsqueda reserva 0.5 créditos por cada 30 anuncios que pide su `limit`, y cobra 0.5 créditos por cada 30 anuncios que devuelve, con un mínimo de 0.5 créditos. La búsqueda predeterminada de 30 anuncios cuesta 0.5 créditos, y una búsqueda con `limit` 300 en la Biblioteca de anuncios reserva 5 créditos. `advertisers` y `ad` cuestan 0.5 créditos cada uno. Solo se cobran las solicitudes completadas.

## Relacionado

* [Bibliotecas de anuncios comparadas](https://docs.querying.ai/es/engines/ad-libraries.md)
* [Biblioteca de anuncios de Meta](https://docs.querying.ai/es/engines/meta-ad-library.md)
* [Resumen de motores](https://docs.querying.ai/es/engines/overview.md)
* [Créditos y límites](https://docs.querying.ai/es/concepts/credits-and-limits.md)


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