{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Library Scraper – Creative Center Top Ads",
    "description": "Export public TikTok Creative Center Top Ads by keyword, country, period, industry, objective, language, and format with ad copy, videos, images, and performance signals.",
    "version": "0.1",
    "x-build-id": "3pgfwhVWs0DSRUI9V"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/fetch_cat~tiktok-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-fetch_cat-tiktok-ads-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/fetch_cat~tiktok-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-fetch_cat-tiktok-ads-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/fetch_cat~tiktok-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-fetch_cat-tiktok-ads-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": {
          "keywords": {
            "title": "Keywords",
            "maxItems": 20,
            "type": "array",
            "description": "Optional ad text or brand keywords to search (maximum 20 per run). Split larger lists into separate runs of at most 20 keywords. Leave empty to return top ads for the selected markets.",
            "items": {
              "type": "string"
            }
          },
          "regions": {
            "title": "Regions / country codes",
            "type": "array",
            "description": "TikTok Creative Center country codes such as US, GB, DE, FR, BR, JP, AU. Use one or a few for focused runs.",
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "Maximum ads",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum number of ad records to save across all keyword and region combinations.",
            "default": 20
          },
          "languages": {
            "title": "Ad languages",
            "maxItems": 20,
            "type": "array",
            "description": "Optional language codes such as en, es, de, fr, pt, ja (maximum 20 per run). Leave empty for all languages.",
            "items": {
              "type": "string"
            }
          },
          "adFormat": {
            "title": "Ad format",
            "pattern": "^\\s*[0-9]*\\s*$",
            "type": "string",
            "description": "Optional numeric Creative Center ad format key as a string, not a label such as video. Leave empty for all formats. Unsupported nonnumeric input is prevented by the schema; local/bypassed invalid inputs produce a visible warning without requests."
          },
          "startUrls": {
            "title": "Creative Center URLs",
            "type": "array",
            "description": "Optional HTTPS ads.tiktok.com Creative Center URLs, as strings or objects with a url field. TikTok profile/video and other unsupported URLs are skipped with a visible warning and RUN_SUMMARY details. If all supplied URLs are unsupported, the run succeeds empty without falling back to unrelated ads. Valid URLs in mixed lists are preserved. Query parameters like keyword, countryCode, and period are used as hints.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "period": {
            "title": "Time period",
            "enum": [
              "7",
              "30",
              "180"
            ],
            "type": "string",
            "description": "Lookback window used by TikTok Creative Center.",
            "default": "7"
          },
          "industries": {
            "title": "Industry keys",
            "maxItems": 20,
            "type": "array",
            "description": "Optional TikTok industry/category keys (maximum 20 per run). Leave empty for all industries.",
            "items": {
              "type": "string"
            }
          },
          "objectives": {
            "title": "Objective keys",
            "maxItems": 20,
            "type": "array",
            "description": "Optional campaign objective keys (maximum 20 per run). Leave empty for all objectives.",
            "items": {
              "type": "string"
            }
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "for_you",
              "ctr",
              "like",
              "cost"
            ],
            "type": "string",
            "description": "Recommended, CTR and Likes use TikTok ranking. Legacy cost collects recommended ads matching your filters and sorts only that bounded sample by cost index, highest first (unknown last), with a visible warning. Not a market-wide cost ranking.",
            "default": "for_you"
          },
          "maxRetries": {
            "title": "Maximum retries",
            "minimum": 0,
            "maximum": 6,
            "type": "integer",
            "description": "Retries for temporary network, rate-limit, server, and Creative Center index errors.",
            "default": 3
          },
          "runtimeSafetySecs": {
            "title": "Runtime safety limit",
            "minimum": 30,
            "maximum": 270,
            "type": "integer",
            "description": "Stops new requests before the platform timeout so completed rows and diagnostics are preserved.",
            "default": 240
          },
          "industryNames": {
            "title": "Industry names (optional)",
            "maxItems": 20,
            "type": "array",
            "description": "English Creative Center names from the catalog verified 3 Nov 2026, e.g. Beauty & Personal Care, Games, or Cosmetics. Case-insensitive exact names. Unknown/ambiguous names reject, never run unfiltered. Combined with legacy raw industries as additional searches; no catalog HTTP request.",
            "items": {
              "type": "string"
            }
          },
          "objectiveNames": {
            "title": "Objective names (optional)",
            "maxItems": 20,
            "type": "array",
            "description": "Traffic, App Installs, Conversions, Video Views, Reach, Lead Generation, or Product sales. Case-insensitive exact names; combined with raw objectives. Unknown names reject before requests.",
            "items": {
              "type": "string"
            }
          },
          "includeAdDetails": {
            "title": "Include public ad details (optional)",
            "type": "boolean",
            "description": "Default off. Add source-backed destination, countries, comments/shares, objectives and source in adDetails. Set maxItems explicitly to 1–6 and use one filter combination. Incompatible optional-mode inputs succeed without requests or rows and explain the required correction in the run warning and RUN_SUMMARY; no silent truncation. Direct access only; no extra billing event. Bounded 120-second source-work budget, up to 20 seconds per request, two concurrent lookups, 100 KB output budget and at most one shared detail retry. Customer timeouts reserve five seconds for saving and shutdown; expected timeout stops preserve completed rows with a warning. Genuine incomplete details fail visibly while preserving useful rows. No video/destination downloads.",
            "default": false
          },
          "adIds": {
            "title": "Direct Creative Center ad IDs (optional)",
            "maxItems": 6,
            "type": "array",
            "description": "Recheck 1–6 known 19-digit Creative Center IDs without discovery. Clear startUrls and discovery filters, including prefilled regions. Automatically enables details. Preserves input ID order and removes duplicates. Empty countryCode and zero periodDays/sourcePage mean no search context, not global coverage. No separate detail charge; direct access only.",
            "items": {
              "type": "string",
              "pattern": "^[0-9]{19}$"
            }
          },
          "includeCreativeMetadata": {
            "title": "Include creative geometry",
            "type": "boolean",
            "description": "Append aspect ratio (width / height, rounded to six decimal places) and portrait/square/landscape orientation from existing video dimensions. Default off; no additional requests or billed events. Slightly increases output size. Not a placement or performance recommendation.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional Apify Proxy configuration for regions or networks where Creative Center blocks direct requests.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}