{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Transcript: Top Ads Hooks, CTAs & Scripts",
    "description": "Get the transcript of top performing TikTok ads from the TikTok Creative Center Top Ads list, with each ad's spoken hook, CTA, offer and angle. Filter by region, industry, objective, period or keyword. Returns brand, likes, CTR and timed segments. $25 per 1,000 ads; ads with no speech are free.",
    "version": "1.0",
    "x-build-id": "zHs135575q0tWlxDj"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/tenfoldfleet~tiktok-ads-transcript/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-tenfoldfleet-tiktok-ads-transcript",
        "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/tenfoldfleet~tiktok-ads-transcript/runs": {
      "post": {
        "operationId": "runs-sync-tenfoldfleet-tiktok-ads-transcript",
        "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/tenfoldfleet~tiktok-ads-transcript/run-sync": {
      "post": {
        "operationId": "run-sync-tenfoldfleet-tiktok-ads-transcript",
        "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": {
          "region": {
            "title": "Region",
            "enum": [
              "AR",
              "AU",
              "BR",
              "CA",
              "CO",
              "FR",
              "DE",
              "ID",
              "IT",
              "JP",
              "MY",
              "MX",
              "NL",
              "PK",
              "PH",
              "RO",
              "SA",
              "SG",
              "ZA",
              "KR",
              "ES",
              "SE",
              "TH",
              "TR",
              "AE",
              "GB",
              "US",
              "VN"
            ],
            "type": "string",
            "description": "Country whose Top Ads you want. TikTok's Top Ads cover these 28 markets.",
            "default": "US"
          },
          "period": {
            "title": "Time period",
            "enum": [
              "7",
              "30",
              "180"
            ],
            "type": "string",
            "description": "How far back TikTok looks when ranking the ads: the last 7, 30 or 180 days.",
            "default": "30"
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "for_you",
              "reach",
              "ctr",
              "likes",
              "cvr",
              "2s_view_rate",
              "6s_view_rate"
            ],
            "type": "string",
            "description": "How TikTok ranks the ads. Different sort orders surface different ads.",
            "default": "for_you"
          },
          "industry": {
            "title": "Industry (optional)",
            "type": "string",
            "description": "Limit to one industry, by the name the Creative Center shows, e.g. \"Games\", \"Beauty & Personal Care\" or a sub-industry as \"Apps > Utilities\". A numeric industry id also works. Leave empty for all industries."
          },
          "objective": {
            "title": "Campaign objective (optional)",
            "type": "string",
            "description": "Limit to one advertising objective, e.g. \"Traffic\", \"App Installs\", \"Conversions\", \"Video Views\", \"Reach\", \"Lead Generation\", \"Product sales\", \"App Promotion\". Leave empty for all objectives."
          },
          "keyword": {
            "title": "Keyword (optional)",
            "type": "string",
            "description": "Brand or product keyword, typed into the Creative Center's own search box, e.g. \"skincare\". Keyword searches return far fewer ads than the plain list."
          },
          "maxAds": {
            "title": "Max ad transcripts",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Stop after this many ads with a transcript. Each one is one charged result ($0.025). Ads without speech (music only, or fewer than 4 spoken words) are free and do not count, so the run looks at up to three times this many ads. On the Apify free plan a run returns up to 3 ad transcripts.",
            "default": 20
          },
          "includeAnalysis": {
            "title": "Add CTA, offer and angle",
            "type": "boolean",
            "description": "Reads each transcript and adds the spoken call to action, the spoken offer and a one-line persuasion angle. Same price either way. The hook (first spoken line) is always returned.",
            "default": true
          },
          "language": {
            "title": "Transcript language hint (optional)",
            "type": "string",
            "description": "Two-letter language code of the speech, e.g. \"en\", \"es\" or \"id\". Leave empty to detect the language of each ad automatically."
          },
          "adUrls": {
            "title": "Specific ads (optional)",
            "type": "array",
            "description": "Creative Center ad links or ad IDs, e.g. \"7696088014783234068\". The run looks these ads up in the Top Ads list for the region, period, industry, objective and keyword above (always sorted by reach, so no listed ad is skipped) and transcribes only them; an ad that is not in that list comes back as a free error row. When this field is filled in, the plain Top Ads list is never transcribed instead. Up to 500 ads per run; on the Apify free plan the first 3 are processed.",
            "items": {
              "type": "string"
            }
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify Proxy (datacenter) works well and is included in the price. Free-plan users can keep the default. Residential and other proxy groups and proxy countries are ignored; your own proxy URLs are used as given.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}