{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Library Scraper | from $0.50/1K Ads, No Login",
    "description": "Scrape the TikTok Commercial Content Library by keyword, advertiser or URL: every ad with call to action, objective, destination URL, targeting and TikTok account. Fixes the library's early end of pagination. No login, no browser per ad.",
    "version": "0.1",
    "x-build-id": "tYC64shTmL0RKfWqX"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/alexmorain~tiktok-ads-library-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-alexmorain-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/alexmorain~tiktok-ads-library-scraper/runs": {
      "post": {
        "operationId": "runs-sync-alexmorain-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/alexmorain~tiktok-ads-library-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-alexmorain-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": {
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "Keyword searches, as in the library search box: every ad whose text or advertiser name matches, from any advertiser. One term per line.",
            "items": {
              "type": "string"
            }
          },
          "exactMatch": {
            "title": "Exact phrase",
            "type": "boolean",
            "description": "Search terms match the exact phrase instead of all the words in any order. <code>just do it</code> as a phrase finds that slogan, not every ad with those three words.",
            "default": false
          },
          "advertisers": {
            "title": "Advertisers",
            "type": "array",
            "description": "Brands whose ads you want, one per line, written as the library shows them (<code>Snipes SE</code>, <code>Nike Retail B.V.</code>). A name is looked up in the library suggestions and <b>only an exact match (case ignored)</b> is followed: the Actor never bills another advertiser's ads. When nothing matches, the log lists the closest names. Only that advertiser's ads come out, not every ad that mentions the brand. Advertisers can have tens of thousands of ads: set Max ads per target.",
            "items": {
              "type": "string"
            }
          },
          "searchUrls": {
            "title": "Search URLs",
            "type": "array",
            "description": "Pages copied from <code>library.tiktok.com/ads?...</code>: the keyword or advertiser, the country (<code>region</code>), the dates (<code>start_time</code>, <code>end_time</code>) and the sort in the URL are kept for that URL. One URL per line.",
            "items": {
              "type": "string"
            }
          },
          "adUrls": {
            "title": "Ad URLs",
            "type": "array",
            "description": "Single ads, <code>https://library.tiktok.com/ads/detail/?ad_id=...</code>. No search: only the detail page of each ad.",
            "items": {
              "type": "string"
            }
          },
          "adIds": {
            "title": "Ad IDs",
            "type": "array",
            "description": "Single ads by ID (a number of 10 to 22 digits), one per line. Same as Ad URLs.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Only ads shown in these countries. Leave empty for all the countries of the library in one search. Several countries are searched one by one and each ad comes out once.",
            "items": {
              "type": "string",
              "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",
                "TR"
              ],
              "enumTitles": [
                "Austria (AT)",
                "Belgium (BE)",
                "Bulgaria (BG)",
                "Switzerland (CH)",
                "Cyprus (CY)",
                "Czechia (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)",
                "Türkiye (TR)"
              ]
            }
          },
          "startDate": {
            "title": "Shown from",
            "type": "string",
            "description": "Only ads shown on or after this date. Empty: 30 days before the end date. The library keeps about a year of ads and refuses a range over 1200 days. Careful: it is a <b>shown</b> date, an ad that started earlier and still ran on this day is kept: read <code>firstShown</code> for the launch date."
          },
          "endDate": {
            "title": "Shown until",
            "type": "string",
            "description": "Only ads shown on or before this date. Empty: today."
          },
          "adStatus": {
            "title": "Ad status",
            "enum": [
              "all",
              "active",
              "inactive"
            ],
            "type": "string",
            "description": "Active ads are the ones running now, inactive ads have stopped.",
            "default": "all"
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "all",
              "video",
              "image"
            ],
            "type": "string",
            "description": "Only video ads, or only image ads. The library often lists an image ad without its image URL, so <code>format</code> is read from the filter you pick when the ad exposes no media.",
            "default": "all"
          },
          "ages": {
            "title": "Targeted ages",
            "type": "array",
            "description": "Only ads that target this age range. Several ranges are searched one by one and merged, since the library does not combine them. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "13-17",
                "18-24",
                "25-34",
                "35-44",
                "45-54",
                "55+"
              ]
            }
          },
          "gender": {
            "title": "Targeted gender",
            "enum": [
              "all",
              "female",
              "male"
            ],
            "type": "string",
            "description": "Only ads that target women or men.",
            "default": "all"
          },
          "reach": {
            "title": "Unique reach",
            "type": "array",
            "description": "Only ads whose estimated unique reach is in this band. Several bands are searched one by one and merged. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "0-10K",
                "10K-100K",
                "100K+"
              ]
            }
          },
          "sortBy": {
            "title": "Sort",
            "enum": [
              "newest",
              "oldest",
              "mostReach",
              "lastShown"
            ],
            "type": "string",
            "description": "Leave empty for the thorough search (see below). Pick a sort to run that single pass only: faster and cheaper to read, but it misses the ads the library loses on that sort."
          },
          "includeDetails": {
            "title": "Full detail of each ad",
            "type": "boolean",
            "description": "On: each ad comes with its detail page (call to action, objective, destination URL, audience size, reach by country, age and gender, targeting, TikTok account) and is billed as an ad with details. Off: the list row only (text, media, advertiser, dates, reach band), billed as a plain ad. A detail the library refuses to give is not billed as a detail: the row comes out with <code>hasDetails: false</code>.",
            "default": true
          },
          "detailLanguage": {
            "title": "Detail language",
            "type": "string",
            "description": "<code>en</code> writes the advertiser's country in English. A full locale such as <code>fr-FR</code> or <code>de-DE</code> writes it in that language; two-letter codes other than <code>en</code> are ignored by the library.",
            "default": "en"
          },
          "maxAdsPerSearch": {
            "title": "Max ads per target",
            "minimum": 0,
            "type": "integer",
            "description": "Stop each search term, advertiser or URL after this many ads. <code>0</code> for no cap: a keyword can reach tens of thousands of ads, a big advertiser more, and each is billed.",
            "default": 1000
          },
          "thoroughness": {
            "title": "Search depth",
            "enum": [
              "complete",
              "fast"
            ],
            "type": "string",
            "description": "<b>Complete</b> (default): the library's search drops pages and says the list ended early; the Actor replays them and merges three sorts, so you get nearly all the ads the library announces (it reports announced against found in the run log and in <code>RUN_SUMMARY</code>). <b>Fast</b>: one sort, with the page replays only.",
            "default": "complete"
          },
          "maxConcurrency": {
            "title": "Parallel lanes",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "How many proxy sessions work at once. Each is one IP with its own access tokens.",
            "default": 4
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "all",
              "new-only"
            ],
            "type": "string",
            "description": "<b>All ads</b> returns every ad the search finds, on every run.<br><br><b>New ads only</b> keeps a persistent registry of the ads previous runs returned and charged, and returns only ads never returned before: schedule it daily to be told when a competitor launches something new. Every run reads the whole search, since the library does not sort by launch date; you pay only for the new ads, and no detail is fetched for the old ones.",
            "default": "all"
          },
          "registryKey": {
            "title": "Registry key (New ads only)",
            "type": "string",
            "description": "By default the registry is tied to the exact targets, countries and filters, so changing any of them starts a fresh one. Set your own key to keep one registry while you edit the list."
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "If set, the Actor POSTs a small JSON summary to this URL at the end of the run, <b>only when at least one ad was returned</b>: <code>actor</code>, <code>runId</code>, <code>mode</code>, <code>items</code>, <code>targets</code>. With New ads only and a daily schedule, that is a push notification when a competitor launches ads.<br><br>Use the final URL: a redirect is not followed, except a 307 or 308, which gets the same POST once. An unreachable webhook is logged as a warning and never fails the run. Stored encrypted."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Leave as is. The library accepts datacenter IPs. With the plain Apify proxy the Actor switches to residential by itself if the library ever refuses them. A browser makes the access tokens; everything else is plain HTTP.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}