{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Search Scraper: Keywords, Hashtags, Creators",
    "description": "Scrape TikTok search results by keyword or hashtag and discover creators. Pay only per result. Views, likes, comments, shares, bookmarks, channel stats, music, subtitles and direct video URLs as JSON. Output compatible with popular TikTok scrapers. No proxies or login needed. Works via API and MCP.",
    "version": "0.1",
    "x-build-id": "xW36ev6jpS7My9syA"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/xmolodtsov~tiktok-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-xmolodtsov-tiktok-search-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/xmolodtsov~tiktok-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-xmolodtsov-tiktok-search-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/xmolodtsov~tiktok-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-xmolodtsov-tiktok-search-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": "Search Keywords",
            "type": "array",
            "description": "Search terms, typed as you would in the TikTok search bar (e.g. <code>ai tools</code>, <code>skincare routine</code>). Each keyword is searched separately (about 200–420 videos per keyword) and all results land in one dataset.<br><br><strong>Tip:</strong> batch many keywords in a single run for the best cost efficiency. Required unless Video URLs are given.",
            "items": {
              "type": "string"
            }
          },
          "videoUrls": {
            "title": "Video URLs",
            "type": "array",
            "description": "Free, opt-in. Public TikTok video/photo URLs, or vm.tiktok.com and www.tiktok.com/t/ links that resolve in one redirect. For URL-only runs, leave keywords empty. URLs run first, then keywords, within one maxItems limit. Unavailable URLs are skipped without an item charge.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "dateRange": {
            "title": "Date range",
            "enum": [
              "ALL",
              "YESTERDAY",
              "THIS_WEEK",
              "THIS_MONTH",
              "LAST_3_MONTHS",
              "LAST_6_MONTHS"
            ],
            "type": "string",
            "description": "Free, opt-in. Rolling lookback from run start: 1, 7, 30, 90 or 180 days. ALL preserves unfiltered search. Search is server-filtered; every source also receives an exact client-side age cutoff. Windows can return fewer results.",
            "default": "ALL"
          },
          "includeSlideshowImages": {
            "title": "Include slideshow image URLs",
            "type": "boolean",
            "description": "Free, opt-in. Add slideshowImages to every row: photo posts carry image URLs and dimensions, other posts carry null. URLs may expire; media is not downloaded.",
            "default": false
          },
          "maxItems": {
            "title": "Maximum number of items on output",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum total number of videos on output, across URLs, keywords and expansion pools. Leave empty for 1,000. On the free Apify plan a run is capped at 100."
          },
          "sortType": {
            "title": "Sort Type",
            "enum": [
              "RELEVANCE",
              "MOST_LIKED",
              "DATE_POSTED"
            ],
            "type": "string",
            "description": "Sort order for search results. Sorting is applied client-side after fetching — TikTok ignores server-side sort parameters.",
            "default": "RELEVANCE"
          },
          "uniqueAuthors": {
            "title": "Unique Authors Only",
            "type": "boolean",
            "description": "Creator discovery: emit at most one video per creator (<code>channel.id</code>), so every item is a different creator. Combine with <code>expansion</code> to find about 10x more creators per keyword.",
            "default": false
          },
          "expansion": {
            "title": "Expansion Pools",
            "type": "array",
            "description": "Opt-in harvest pools that multiply the number of <strong>new creators</strong> per keyword ~10x. On top of the classic keyword search, the Actor harvests TikTok's search suggestions, hashtag feeds and sound feeds — all seeded from the keyword's own search results, and every item still carries the original keyword.<br><br>Leave empty for classic keyword search only. Available on paid Apify plans; free-plan runs use classic search only.",
            "items": {
              "type": "string",
              "enum": [
                "suggest",
                "hashtag",
                "music"
              ],
              "enumTitles": [
                "Search suggestions",
                "Hashtag feeds",
                "Sound/music feeds"
              ]
            },
            "default": []
          },
          "relevanceThreshold": {
            "title": "Relevance Threshold (music pool)",
            "minimum": 0,
            "maximum": 1,
            "type": "number",
            "description": "Topicality gate for the sound/music pool: the fraction of a sound's first page of captions that must match the seed keyword or its hashtags before that sound is crawled in depth. Higher = stricter, fewer sounds. Used only when the music pool is on.",
            "default": 0.3
          },
          "commentsPerPost": {
            "title": "Comments per video",
            "minimum": 0,
            "maximum": 200,
            "type": "integer",
            "description": "Paid add-on: attach up to this many top comments to each video as <code>commentList</code>. Each comment (and each reply) returned is charged as one <code>comment</code> event, see Pricing. 0 = off. Paid Apify plans only.",
            "default": 0
          },
          "maxRepliesPerComment": {
            "title": "Replies per comment",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Paid add-on: attach up to this many replies to each comment in <code>commentList</code> (as <code>replies</code>). Each reply is charged as one <code>comment</code> event. Used only when <code>commentsPerPost</code> is above 0. 0 = no replies.",
            "default": 0
          },
          "includeAuthorProfile": {
            "title": "Include creator profile",
            "type": "boolean",
            "description": "Paid add-on: attach the creator's profile page details as <code>authorProfile</code> (bio, bio link, account creation time, language, friends, business and seller flags, live status). Fetched and charged once per unique creator per run as one <code>author-profile</code> event, see Pricing; later videos of the same creator carry it free.",
            "default": false
          },
          "includeTranscript": {
            "title": "Include native transcript",
            "type": "boolean",
            "description": "Paid add-on, native TikTok captions only (no speech-to-text): about half of posts have them; charged only per transcript delivered. Adds transcript: {lang, source, text}, or null when captions are missing or unavailable. Paid Apify plans only; requires a live transcript pricing event.",
            "default": false
          },
          "transcriptLanguage": {
            "title": "Preferred transcript language",
            "type": "string",
            "description": "Optional language code, e.g. en. An available matching track wins; otherwise use the post's own track, preferring creator captions, then ASR, then machine translation. Does not translate captions.",
            "default": ""
          },
          "downloadVideos": {
            "title": "Download videos",
            "type": "boolean",
            "description": "Paid add-on, opt-in: save MP4 files in the run’s key-value store and attach videoFile metadata (null when unavailable). Paid plans only; requires a live event for the requested quality. Charged only after successful storage, for the delivered class. Files above 64 MB are skipped. The run’s storage follows your Apify data retention.",
            "default": false
          },
          "videoQuality": {
            "title": "Video quality",
            "enum": [
              "540p",
              "720p",
              "1080p"
            ],
            "type": "string",
            "description": "Used with downloadVideos. Select the smallest file in this resolution class (shorter dimension); if missing, try the next lower priced class. Charge only the delivered class as video-download-540p, video-download-720p or video-download-1080p. Codecs may include HEVC; no transcoding.",
            "default": "540p"
          },
          "maxItemsPerKeyword": {
            "title": "Maximum items per keyword",
            "minimum": 1,
            "type": "integer",
            "description": "Optional cap of results per single keyword. Keywords are processed sequentially against the global <code>maxItems</code> budget."
          },
          "maxPostsPerAuthor": {
            "title": "Maximum posts per author",
            "minimum": 1,
            "type": "integer",
            "description": "Cap on items per creator in the classic search (relevance) results — the expansion pools always emit at most one item per creator regardless of this value (leave empty for no cap)."
          },
          "includeSearchKeywords": {
            "title": "Include Search Keywords",
            "type": "boolean",
            "description": "If enabled, each result includes the <code>keyword</code> and <code>inputSource</code> fields with the search keyword that found it.",
            "default": true
          },
          "location": {
            "title": "Location / Region",
            "type": "string",
            "description": "Cosmetic. Passed to TikTok as the <code>region</code> parameter (ISO 3166-1 alpha-2 code, e.g. <code>US</code>), but TikTok picks results by the request's IP address, so this does <strong>not</strong> return per-country results.",
            "default": "US"
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration (optional)",
            "type": "object",
            "description": "Leave empty — proxies are built in and included in the price. To route through your own proxies, enter their URLs here; the Apify Proxy option is not used on paid plans. Free-plan runs use Apify Proxy unless you enter your own URLs.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}