{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Scraper — Creative Center TikTok Top Ads Transcripts",
    "description": "TikTok Creative Center Top Ads as transcripts with the first-3s hook, CTR and brand metadata, one row per ad. Pick a region, no ad IDs needed; or paste ad links or chain any scraper. From $8.00 per 1,000 ad video transcripts, 3 min included. Expired links and music-only ads are never charged.",
    "version": "1.0",
    "x-build-id": "ZsEMdfmWFGQjKeO1v"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/steadyfetch~tiktok-ads-transcript-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-steadyfetch-tiktok-ads-transcript-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/steadyfetch~tiktok-ads-transcript-scraper/runs": {
      "post": {
        "operationId": "runs-sync-steadyfetch-tiktok-ads-transcript-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/steadyfetch~tiktok-ads-transcript-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-steadyfetch-tiktok-ads-transcript-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": {
          "discoverRegion": {
            "title": "Region",
            "type": "string",
            "description": "The ad market to pull Creative Center Top Ads from, e.g. \"US\" — pick one and the actor finds the ads itself, or leave it empty and supply your own ads below. Finding ads is never charged, and neither is a silent or music-only ad or an expired video link. A video or audio file on any other host goes to steadyfetch/media-transcriber. Leave it empty with nothing else set and the run is a 3-ad sample from the United States (all industries, short ads, charged like any run) — the fastest way to see real output.",
            "default": ""
          },
          "discoverIndustry": {
            "title": "Industry (optional)",
            "type": "string",
            "description": "Narrow discovery to one industry. Leave it on 'All industries' to see the strongest ads in the region regardless of category.",
            "default": ""
          },
          "discoverPeriod": {
            "title": "Time window",
            "type": "string",
            "description": "How far back to look for top-performing ads.",
            "default": "30"
          },
          "discoverSort": {
            "title": "Rank ads by",
            "type": "string",
            "description": "Which ads to take first: TikTok's own recommendation, click-through rate, or likes.",
            "default": "for_you"
          },
          "discoverMaxAds": {
            "title": "How many ads to find",
            "minimum": 1,
            "type": "integer",
            "description": "How many discovered ads to transcribe. Each delivered transcript is charged, so this is your cost dial for a discovery run — start small. Up to 100 per run; ask for a bigger number and the run continues at 100, with one uncharged row saying so.",
            "default": 20
          },
          "videoUrls": {
            "title": "Ad video URLs or ad page links",
            "type": "array",
            "description": "TikTok CDN video links (*.tiktokcdn.com) — the videoUrl / videoUrl720p / video_url field from any Creative Center scraper result. Ad page links copied while browsing Creative Center (ads.tiktok.com/business/creativecenter/topads/…) work here too — a fresh video link is fetched for each. A direct audio or video FILE on any other host is not read here — that goes to our media transcriber (apify.com/steadyfetch/media-transcriber), pasted into its \"Media URLs\" field; a link here that is not a TikTok one comes back as an uncharged row saying so.",
            "items": {
              "type": "string"
            }
          },
          "materialIds": {
            "title": "Material IDs or ad page links",
            "type": "array",
            "description": "Creative Center Top Ads material IDs (the long id in scraper results) or ad page links (ads.tiktok.com/business/creativecenter/topads/…). The actor fetches a fresh video link for each — useful when your scraped video URLs have already expired.",
            "items": {
              "type": "string"
            }
          },
          "datasetId": {
            "title": "Dataset ID (chain a scraper run)",
            "type": "string",
            "description": "The default dataset ID of a finished Creative Center scraper run: the first 10,000 rows are read and up to maxAds ads (1,000 by default, 10,000 at most) are processed per run. Ads this account already has are handed back uncharged and do not count against maxAds, so a re-run of the same dataset carries on with what is new. With Apify's 'Connect actor' integration this is filled automatically — the cleanest way to chain."
          },
          "datasetItems": {
            "title": "Dataset items (paste rows)",
            "type": "array",
            "description": "Paste rows from your Creative Center scraper run. The actor deep-scans each row for the ad video URL + metadata (brand, title, CTR, material ID) — works with any scraper's output shape. Leave it empty to use discovery or the other inputs instead."
          },
          "watchlistId": {
            "title": "Watchlist name",
            "type": "string",
            "description": "A short name for the list, e.g. `beauty-us` (letters, numbers and hyphens). The list lives in a named key-value store in your account called `tiktok-ads-watch-<name>`, so you can inspect or clear it any time. Leave empty for a one-off run — your account's memory of delivered ads still applies."
          },
          "newAdsOnly": {
            "title": "New ads only",
            "type": "boolean",
            "description": "OFF (default): every ad runs as usual; an ad your account already has comes back from the earlier run, not charged (`repeat: true`), and every row carries `isNew` / `firstSeenAt`. ON: ads already on your watchlist — or, with no list name, already delivered to your account — are skipped before download: not fetched, not charged, and the run's status line and OUTPUT say how many. Only an ad the actor actually answered counts (a delivered transcript or on-screen text, or a final uncharged verdict such as no speech); an ad it could not answer — an expired link, a failed download, an ad your cost cap left out — does not, so the next run tries it again.",
            "default": false
          },
          "includeOnScreenText": {
            "title": "Read on-screen text on silent video ads",
            "type": "boolean",
            "description": "OFF (default): an ad with no speech is never charged. ON: silent and music-only ads have their on-screen text read from the video's own frames and delivered as `onScreenText`, charged like a transcript (same event, same price — never the \"Extra video minute\" surcharge). Ads with no readable on-screen text stay uncharged either way.",
            "default": false
          },
          "maxAds": {
            "title": "Max ads to process",
            "minimum": 1,
            "type": "integer",
            "description": "Safety cap on how many ads to transcribe in one run. Up to 10,000 per run; ask for a bigger number and the run continues at 10,000, with one uncharged row saying so. Long videos: the first 3 minutes of every video are included in the transcript price; each started minute beyond that is charged as an \"Extra video minute\" at $0.005 — only when the transcript is delivered, never on on-screen text.",
            "default": 1000
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}