{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Library Scraper",
    "description": "Search TikTok's public Ads Library by advertiser, keyword, business ID, or copied library URL. Returns creative media, advertiser, status, dates, audience estimates, targeting details, and source links. Use for EU/EEA competitor-ad research. Costs $0.006 per ad plus $0.00005 start.",
    "version": "1.1",
    "x-build-id": "d8IwM1dThflvqFeqH"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~tiktok-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~tiktok-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-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/khadinakbar~tiktok-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-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": {
          "libraryUrl": {
            "title": "TikTok Ads Library URL",
            "maxLength": 4096,
            "type": "string",
            "description": "Use this when you already have a filtered https://library.tiktok.com/ads URL to reproduce exactly. Paste a URL containing region, date range, and advertiser or keyword filters, for example https://library.tiktok.com/ads?region=DE&adv_name=adidas&query_type=1. Its filters override the individual search fields. Do not paste a TikTok profile, ad-detail, Creative Center, or Ads Manager URL."
          },
          "country": {
            "title": "Ad target country",
            "enum": [
              "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"
            ],
            "type": "string",
            "description": "Use this when building a public Ads Library search rather than pasting libraryUrl. Select an EEA country, Switzerland, or the United Kingdom where TikTok exposes the ad record, for example DE for Germany. Defaults to DE and also selects a matching residential browser session. This is not the country where your own company is located.",
            "default": "DE"
          },
          "searchQuery": {
            "title": "Advertiser or keyword",
            "maxLength": 200,
            "type": "string",
            "description": "Use this when searching the public library by advertiser name or words in an ad, for example adidas. It accepts one phrase and defaults to adidas for a working health-check search. Choose searchType to say whether the phrase is a keyword or advertiser-name search. This is not an ad ID, TikTok handle, or profile URL.",
            "default": "adidas"
          },
          "searchType": {
            "title": "Search interpretation",
            "enum": [
              "keyword",
              "advertiser"
            ],
            "type": "string",
            "description": "Use this to tell TikTok whether searchQuery is a keyword or an advertiser name. Choose keyword for words appearing in creatives and advertiser for a brand, for example adidas AG. Defaults to keyword and only changes the public library search interpretation. It does not perform an exact business-ID lookup; use advertiserBusinessId for that.",
            "default": "keyword"
          },
          "advertiserBusinessId": {
            "title": "Advertiser business ID",
            "pattern": "^$|^[0-9]{1,30}$",
            "maxLength": 30,
            "type": "string",
            "description": "Use this when you know TikTok's advertiser business ID and need an exact advertiser filter. Enter digits such as 6885261436319171329; it can be combined with searchQuery. Leave blank when you only know a brand name or keyword. This is not an ad ID or a TikTok user ID."
          },
          "dateFrom": {
            "title": "First shown from",
            "pattern": "^$|^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "maxLength": 10,
            "type": "string",
            "description": "Use this to set the inclusive beginning of the public-library date range in YYYY-MM-DD format, for example 2026-01-01. If omitted, the actor uses the preceding 90 days to keep searches bounded and predictable. Use an earlier date only when the target country and advertiser need historical coverage. This is not a time zone, timestamp, or an ad creation-date guarantee."
          },
          "dateTo": {
            "title": "Last shown through",
            "pattern": "^$|^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "maxLength": 10,
            "type": "string",
            "description": "Use this to set the inclusive end of the public-library date range in YYYY-MM-DD format, for example 2026-03-31. If omitted, the actor uses the time the run starts. It must be on or after dateFrom. This is not a duration, a relative date phrase, or a future schedule."
          },
          "maxResults": {
            "title": "Maximum ads",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Use this to cap validated Ads Library records written to the dataset. Enter an integer from 1 to 200; the default is 20 and each saved record charges the ad-scraped event. Keep it small for a quick check and raise it only for a bounded research job. This is not a page count or a guarantee that TikTok has that many matches.",
            "default": 20
          },
          "includeDetails": {
            "title": "Fetch public ad details",
            "type": "boolean",
            "description": "Use this when you need the public detail endpoint's advertiser, targeting, audience-size, and region breakdown fields. It defaults to false to keep runs fast and adds a detail-enriched event only after a detail response succeeds. Enable it for compliance or targeting analysis, not for a basic creative swipe file. It never accesses private advertiser or Ads Manager data.",
            "default": false
          },
          "requestTimeoutSecs": {
            "title": "Request timeout seconds",
            "minimum": 20,
            "maximum": 120,
            "type": "integer",
            "description": "Use this to set the navigation and public-library request timeout in seconds. Enter a value from 20 to 120; the default is 60 and retries rotate the residential browser session. Increase it only for a slow target response, not to bypass an access block. This is not the overall Apify run timeout.",
            "default": 60
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}