{
  "openapi": "3.0.1",
  "info": {
    "title": "Tiktok Video Scraper",
    "description": "Extract TikTok video metadata including caption, hashtags, mentions, views, likes, comments, shares, saves, author info, music data, and video details. Includes analytics like engagement rate and viral score. Ideal for marketing research, influencer analysis, and AI datasets.",
    "version": "0.3",
    "x-build-id": "Hh0AKZOerwO7bxWkZ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/coregent~tiktok-video-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-coregent-tiktok-video-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/coregent~tiktok-video-scraper/runs": {
      "post": {
        "operationId": "runs-sync-coregent-tiktok-video-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/coregent~tiktok-video-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-coregent-tiktok-video-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": {
          "videos": {
            "title": "Videos (URLs or IDs)",
            "type": "array",
            "description": "TikTok videos to scrape — provide either full video URLs or bare numeric IDs (you can mix both). Examples: https://www.tiktok.com/@creator/video/7352847293847291 or 7352847293847291",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "findVideosBy": {
            "title": "Find videos by creator, hashtag, or keyword",
            "type": "array",
            "description": "Discover videos by @creator, #hashtag, or search keyword — mix them freely, one per line; each entry's type is detected automatically. To scrape specific known videos, use the Videos field above instead. Results are capped by 'Max videos' per entry. If this and Videos are both empty, the actor falls back to searching 'trending'.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "maxVideos": {
            "title": "Max videos per creator / hashtag / keyword",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Maximum videos to scrape from each entry in 'Find videos by' (creator, hashtag, or keyword). Does NOT apply to the Videos field above — every video URL/ID you provide is always scraped (one record each).",
            "default": 50
          },
          "scrapeRelatedVideos": {
            "title": "Scrape related videos",
            "type": "boolean",
            "description": "For video-URL sources, also scrape the source creator's other recent videos for each input video. Note: this is the creator's own recent posts, not TikTok's personalized algorithmic recommendations.",
            "default": false
          },
          "maxRelatedVideos": {
            "title": "Max related videos",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "How many of the source creator's other recent videos to scrape per input video (only used when 'Scrape related videos' is on).",
            "default": 10
          },
          "shouldDownloadVideos": {
            "title": "Download videos",
            "type": "boolean",
            "description": "Download the MP4 and store it permanently on Apify (the output `downloadAddr`/`mediaUrls` point to it). Off by default — downloading uses bandwidth and storage.",
            "default": false
          },
          "shouldDownloadCovers": {
            "title": "Download video covers",
            "type": "boolean",
            "description": "Download video cover/thumbnail images and re-host them on Apify (permanent URLs).",
            "default": false
          },
          "shouldDownloadAvatars": {
            "title": "Download author avatars",
            "type": "boolean",
            "description": "Download author avatar images and re-host them on Apify (permanent URLs).",
            "default": false
          },
          "shouldDownloadMusicCovers": {
            "title": "Download music covers",
            "type": "boolean",
            "description": "Download sound/music cover art and re-host it on Apify (permanent URLs).",
            "default": false
          },
          "shouldDownloadSlideshowImages": {
            "title": "Download slideshow images",
            "type": "boolean",
            "description": "For photo/slideshow posts, download each image and re-host it on Apify (permanent URLs).",
            "default": false
          },
          "videoDownloadQuality": {
            "title": "Video download quality",
            "enum": [
              "low",
              "high"
            ],
            "type": "string",
            "description": "Quality of the re-hosted MP4 when 'Download videos' is on. 'low' picks the smallest bitrate variant (much less residential bandwidth/cost); 'high' keeps the full-res/no-watermark file.",
            "default": "low"
          },
          "videoKvStoreIdOrName": {
            "title": "Media storage name",
            "type": "string",
            "description": "Optional: name or ID of a key-value store to hold downloaded media. Defaults to the run's default store."
          },
          "downloadSubtitlesOptions": {
            "title": "Subtitles / transcript",
            "enum": [
              "off",
              "subtitles",
              "transcript"
            ],
            "type": "string",
            "description": "Extract TikTok's native captions. 'subtitles' adds subtitle track links; 'transcript' also downloads the auto-caption and re-hosts a plain-text transcript (`transcriptionLink`).",
            "default": "off"
          },
          "videoSearchDateFilter": {
            "title": "Posted within",
            "enum": [
              "all",
              "24h",
              "7d",
              "30d",
              "90d",
              "180d"
            ],
            "type": "string",
            "description": "Only keep videos posted within this window (by post date). Applies to all sources.",
            "default": "all"
          },
          "includeReposts": {
            "title": "Include reposted videos",
            "type": "boolean",
            "description": "Also include videos the creator reposted, not just their own posts. Off = the creator's own videos only.",
            "default": false
          },
          "profileSorting": {
            "title": "Sort videos by",
            "enum": [
              "latest",
              "popular",
              "oldest"
            ],
            "type": "string",
            "description": "Order of returned videos for profile sources.",
            "default": "latest"
          },
          "mostDiggs": {
            "title": "Max likes",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos with at most this many likes. Leave empty for no upper bound."
          },
          "leastDiggs": {
            "title": "Min likes",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos with at least this many likes. Leave empty for no lower bound."
          },
          "minCreatorFollowers": {
            "title": "Minimum creator followers",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos whose creator has at least this many followers. Leave empty for no lower bound."
          },
          "maxCreatorFollowers": {
            "title": "Maximum creator followers",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos whose creator has at most this many followers. Leave empty for no upper bound."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}