{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ad Library & Creative Center Scraper",
    "description": "Scrape TikTok ads from the public Ad Library (EEA, UK, Switzerland, Turkey) and the Creative Center: advertiser & sponsor, dates shown, audience reached, creatives, landing page & targeting. Search by advertiser, region & date; monitor new ads. Independent tool, not affiliated with TikTok/ByteDance.",
    "version": "0.1",
    "x-build-id": "9avzgMyGGyY6XJcAL"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~tiktok-ad-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-tiktok-ad-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/scrapesage~tiktok-ad-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-tiktok-ad-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/scrapesage~tiktok-ad-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-tiktok-ad-library-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "source": {
            "title": "Source",
            "enum": [
              "library",
              "creative-center"
            ],
            "type": "string",
            "description": "Where to pull ads from. **Ad Library** = TikTok's public Commercial Content Library (library.tiktok.com): every ad shown in the EEA, UK, Switzerland and Turkey, with advertiser, dates shown, unique users reached and creatives - keyless and reliable. **Creative Center** = the Top Ads ranking; since TikTok's 2026 platform change it serves anonymous sessions an empty list, so it usually returns nothing without a logged-in TikTok session.",
            "default": "library"
          },
          "libraryRegions": {
            "title": "Ad Library regions",
            "type": "array",
            "description": "Ad Library only. Which region editions to search; each region is read separately. ALL searches every region at once.",
            "items": {
              "type": "string",
              "enum": [
                "ALL",
                "AT",
                "BE",
                "BG",
                "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",
                "TR"
              ],
              "enumTitles": [
                "All regions (ALL)",
                "Austria (AT)",
                "Belgium (BE)",
                "Bulgaria (BG)",
                "Switzerland (CH)",
                "Cyprus (CY)",
                "Czech Republic (CZ)",
                "Germany (DE)",
                "Denmark (DK)",
                "Estonia (EE)",
                "Spain (ES)",
                "Finland (FI)",
                "France (FR)",
                "United Kingdom (GB)",
                "Greece (GR)",
                "Croatia (HR)",
                "Hungary (HU)",
                "Ireland (IE)",
                "Iceland (IS)",
                "Italy (IT)",
                "Liechtenstein (LI)",
                "Lithuania (LT)",
                "Luxembourg (LU)",
                "Latvia (LV)",
                "Malta (MT)",
                "Netherlands (NL)",
                "Norway (NO)",
                "Poland (PL)",
                "Portugal (PT)",
                "Romania (RO)",
                "Sweden (SE)",
                "Slovenia (SI)",
                "Slovakia (SK)",
                "Turkey (TR)"
              ]
            },
            "default": [
              "GB"
            ]
          },
          "advertiserName": {
            "title": "Advertiser search (Ad Library)",
            "type": "string",
            "description": "Ad Library only. The library's search box: matches advertiser names, e.g. `Nike` returns NIKE Retail B.V., `protein` returns every advertiser with protein in its name. Leave empty to browse every advertiser in the region."
          },
          "libraryStartDate": {
            "title": "Shown from (Ad Library)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Ad Library only. Earliest date the ad was shown, YYYY-MM-DD. Default: 30 days before the end date."
          },
          "libraryEndDate": {
            "title": "Shown until (Ad Library)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Ad Library only. Latest date the ad was shown, YYYY-MM-DD. Default: today."
          },
          "librarySortBy": {
            "title": "Sort (Ad Library)",
            "enum": [
              "last_shown_date,desc",
              "last_shown_date,asc",
              "create_time,desc",
              "create_time,asc",
              "posted_date,desc",
              "posted_date,asc",
              "impression,desc",
              "impression,asc",
              "video_views,desc",
              "video_views,asc"
            ],
            "type": "string",
            "description": "Ad Library only. Order of the results.",
            "default": "last_shown_date,desc"
          },
          "includeRawData": {
            "title": "Include raw API record (Ad Library)",
            "type": "boolean",
            "description": "Ad Library only. Attach TikTok's raw ad record (and raw detail record when details are on) to every row as `rawItem` / `rawDetail`, for fields not yet mapped.",
            "default": false
          },
          "countryCodes": {
            "title": "Countries / regions (Creative Center)",
            "type": "array",
            "description": "Creative Center only. Which TikTok Creative Center country editions to pull Top Ads from, by ISO code (e.g. US, GB, DE, FR, BR, JP, SG, ID). Each country is scraped separately. Supported: US, GB, CA, AU, DE, FR, IT, ES, BR, MX, AR, CO, JP, KR, ID, TH, VN, MY, PH, SG, SA, AE, EG, TR, RU, IN, NG, PK. Leave default for the United States.",
            "default": [
              "US"
            ],
            "items": {
              "type": "string"
            }
          },
          "period": {
            "title": "Time window",
            "enum": [
              "7",
              "30",
              "180"
            ],
            "type": "string",
            "description": "Creative Center only. Performance window the Top Ads ranking is computed over.",
            "default": "7"
          },
          "orderBy": {
            "title": "Rank ads by",
            "enum": [
              "for_you",
              "ctr",
              "like"
            ],
            "type": "string",
            "description": "Creative Center only. How TikTok ranks the returned ads. \"Recommended\" is TikTok's blended For-You ranking; or rank purely by click-through rate or by likes.",
            "default": "for_you"
          },
          "industries": {
            "title": "Industries (optional)",
            "type": "array",
            "description": "Creative Center only. Filter ads by advertiser industry — by name (e.g. \"Beauty & Personal Care\", \"Apparel & Accessories\", \"Games\", \"E-commerce\", \"Food & Beverage\", \"Financial Services\") or numeric industry id. Each industry is scraped separately. Leave empty for all industries.",
            "items": {
              "type": "string"
            }
          },
          "objectives": {
            "title": "Ad objectives (optional)",
            "type": "array",
            "description": "Creative Center only. Filter by campaign objective — Traffic, App Installs, Conversions, Video Views, Reach, Lead Generation, Product Sales — by name or id. Leave empty for all objectives.",
            "items": {
              "type": "string"
            }
          },
          "adLanguages": {
            "title": "Ad languages (optional)",
            "type": "array",
            "description": "Creative Center only. Filter by the language of the ad creative, by code (e.g. en, es, ar, vi, th, de, fr, pt, id, ja, ko). Leave empty for all languages.",
            "items": {
              "type": "string"
            }
          },
          "includeAdDetails": {
            "title": "Enrich each ad with full details",
            "type": "boolean",
            "description": "Ad Library: read each ad's detail record (targeting: age, gender, locations, extra parameters). Creative Center: open each ad's detail page to add the advertiser LANDING-PAGE URL, every country the ad runs in, comment & share counts, the CTR percentile rank, the objective breakdown and ad keywords. Adds one fast page load per ad (billed as an ad-detail event). Off by default for speed.",
            "default": false
          },
          "maxResults": {
            "title": "Max ads",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum number of ads to return across all regions (Ad Library) or country × industry × objective views (Creative Center) combined. Each TikTok filter view exposes up to a few hundred ranked ads. Keep modest for fast, cheap runs.",
            "default": 100
          },
          "maxResultsPerQuery": {
            "title": "Max ads per filter view",
            "minimum": 0,
            "type": "integer",
            "description": "Cap the number of ads taken from each individual country × industry × objective view (0 = no per-view cap, bounded only by Max ads). Useful for breadth across many views.",
            "default": 0
          },
          "monitorMode": {
            "title": "Monitor mode (only new ads)",
            "type": "boolean",
            "description": "Remember ad IDs seen on previous runs and emit only NEWLY-appearing ads. Ideal on a schedule to track new competitor / industry creatives over time. Works independently of Apify Schedules.",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor key",
            "type": "string",
            "description": "Name this monitor's memory so different saved searches track new ads separately (e.g. \"us-beauty\").",
            "default": "default"
          },
          "includeVideoUrl": {
            "title": "Include direct video download URL",
            "type": "boolean",
            "description": "Include the direct (no-watermark) MP4 creative URL for each ad. These are temporary TikTok CDN links that expire after a few hours — fetch promptly. The permanent cover image and the Creative Center link are always included.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify Proxy used for the headless browser. RESIDENTIAL is the reliable default for both sources; the Creative Center returns no data to datacenter IPs.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ],
              "apifyProxyCountry": "US"
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}