{
  "openapi": "3.0.1",
  "info": {
    "title": "Douyin Scraper - Videos, Creators, Comments & Hot Search",
    "description": "Scrape Douyin (抖音) videos by URL, creator or hashtag: caption, likes, comments, shares, saves, author stats, music, no-watermark MP4 link, tags. Plus creator profiles, comments, danmaku, related videos and the 5 hot-search boards. Filters, monitor mode, no login.",
    "version": "0.1",
    "x-build-id": "keg7qnbI5u6pjb3E4"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/topapi~douyin-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-topapi-douyin-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/topapi~douyin-scraper/runs": {
      "post": {
        "operationId": "runs-sync-topapi-douyin-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/topapi~douyin-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-topapi-douyin-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": {
          "videoUrls": {
            "title": "🎬 Video URLs or IDs",
            "type": "array",
            "description": "Douyin video or photo-post links, e.g. \"https://www.douyin.com/video/7577614489533680959\", \"https://v.douyin.com/iRNBho6u/\", \"https://www.douyin.com/?modal_id=7577614489533680959\" or a bare id. One video row each, duplicates removed.",
            "items": {
              "type": "string"
            }
          },
          "profileUrls": {
            "title": "👤 Creator URLs or sec_uids",
            "type": "array",
            "description": "Creator pages, e.g. \"https://www.douyin.com/user/MS4wLjABAAAA...\", a v.douyin.com share link to a creator, or the bare sec_uid (MS4wLjABAAAA...). Returns the creator's profile row and newest videos.",
            "items": {
              "type": "string"
            }
          },
          "hashtags": {
            "title": "#️⃣ Hashtag URLs or IDs",
            "type": "array",
            "description": "Hashtag pages or ids, e.g. \"https://www.douyin.com/hashtag/1594485689837575\" or \"1594485689837575\". Returns the hashtag's top 15 videos as full video rows, with the hashtag's name and view count on each row.",
            "items": {
              "type": "string"
            }
          },
          "trendingBoards": {
            "title": "🔥 Hot-search boards",
            "type": "array",
            "description": "Douyin's live hot-search boards; about 50 topics each with rank, hot value, video count and event time. Leave empty for none.",
            "items": {
              "type": "string",
              "enum": [
                "hot",
                "seeding",
                "entertainment",
                "social",
                "challenge"
              ],
              "enumTitles": [
                "热榜 Hot search (~50 + trending)",
                "种草榜 Seeding",
                "娱乐榜 Entertainment",
                "社会榜 Social",
                "挑战榜 Challenge"
              ]
            }
          },
          "profileSort": {
            "title": "↕️ Creator video order",
            "enum": [
              "latest",
              "popular"
            ],
            "type": "string",
            "description": "Latest returns the newest videos by publish date: a video the creator pinned counts at its own date (Douyin's page lists pinned videos first; switch on Exclude pinned videos to drop them). Popular sorts the creator's newest ~44 videos by likes and returns the top ones.",
            "default": "latest"
          },
          "postedAfter": {
            "title": "📅 Published after",
            "type": "string",
            "description": "Absolute date (2026-09-01), relative (7 days, 3 weeks, 2 months) or a day count (1 = today). Empty = no lower bound."
          },
          "postedBefore": {
            "title": "📅 Published before",
            "type": "string",
            "description": "Same formats as above. Empty = no upper bound."
          },
          "excludePinnedPosts": {
            "title": "📌 Exclude pinned videos",
            "type": "boolean",
            "description": "Skip the videos a creator pinned to the top of the page.",
            "default": false
          },
          "minLikes": {
            "title": "❤️ Minimum likes",
            "minimum": 0,
            "maximum": 1000000000,
            "type": "integer",
            "description": "Only videos with at least this many likes. 0 = no minimum.",
            "default": 0
          },
          "mediaType": {
            "title": "🎞️ Post type",
            "enum": [
              "all",
              "video",
              "images"
            ],
            "type": "string",
            "description": "Keep videos, photo slideshows or both.",
            "default": "all"
          },
          "keywordFilter": {
            "title": "🔤 Keyword filter",
            "type": "string",
            "description": "Comma-separated words; keep only videos whose caption, hashtags or author name contain one of them, e.g. \"美食, 探店\". Empty = keep all."
          },
          "includeProfile": {
            "title": "👤 Creator profile rows",
            "type": "boolean",
            "description": "One profile row per creator: followers, following, total likes, video count, bio, IP location, verification.",
            "default": true
          },
          "includeComments": {
            "title": "💬 Comments",
            "type": "boolean",
            "description": "Comment rows for every video from your lists (text, likes, reply count, commenter, IP label, date). Douyin does not show reply threads to signed-out visitors, so replies are not included. Related videos are not expanded.",
            "default": false
          },
          "maxCommentsPerVideo": {
            "title": "Max comments per video",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Top-level comments per video, in Douyin's own order (popular first, not by date), 20 per page.",
            "default": 20
          },
          "includeDanmaku": {
            "title": "💭 Danmaku (bullet comments)",
            "type": "boolean",
            "description": "The on-screen bullet comments of every video from your lists, with their time in the video.",
            "default": false
          },
          "maxDanmakuPerVideo": {
            "title": "Max danmaku per video",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Bullet comments per video, in video-time order.",
            "default": 200
          },
          "includeRelated": {
            "title": "🔗 Related videos",
            "type": "boolean",
            "description": "Douyin's related-video list for every video row from your lists delivered in this run (up to 10 each), as full video rows with relatedTo set. Not with Comments only, and not for a video a monitor run skips as delivered before.",
            "default": false
          },
          "maxRelatedPerVideo": {
            "title": "Max related videos per video",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Related videos per video (Douyin lists about 10).",
            "default": 10
          },
          "downloadVideos": {
            "title": "📥 Save MP4 files",
            "type": "boolean",
            "description": "Save each video's MP4 (no watermark) to a key-value store; the row's videoFile.kvUrl points to it. Paid add-on per saved file.",
            "default": false
          },
          "downloadQuality": {
            "title": "MP4 quality",
            "enum": [
              "standard",
              "highest"
            ],
            "type": "string",
            "description": "Which file Save MP4 files stores. Both are without watermark; videoMeta.downloadUrl on every video row (not on photo posts) is the highest one.",
            "default": "standard"
          },
          "downloadCovers": {
            "title": "🖼️ Save cover images",
            "type": "boolean",
            "description": "Save each video's cover image to the key-value store (coverFile.kvUrl). Free.",
            "default": false
          },
          "maxDownloadSizeMb": {
            "title": "Max MP4 size (MB)",
            "minimum": 1,
            "maximum": 150,
            "type": "integer",
            "description": "Larger files are skipped (not saved, not charged). Up to 150 MB; long videos run 100-400 MB.",
            "default": 50
          },
          "kvStoreName": {
            "title": "Key-value store name",
            "type": "string",
            "description": "Save files to this named store (kept across runs), e.g. \"douyin-videos\". Empty = the run's own store."
          },
          "monitorMode": {
            "title": "🔁 Only new rows",
            "type": "boolean",
            "description": "Skip videos, comments and danmaku delivered by earlier runs; a creator's profile row comes on the first run and again only with a run that finds new videos (with maxVideosPerProfile 0: again whenever the creator's counts, name or bio changed). Hot boards return only topics that are NEW, moved rank (CHANGED) or dropped off (EXPIRED).",
            "default": false
          },
          "monitorStoreName": {
            "title": "Monitor memory name",
            "type": "string",
            "description": "Named key-value store that remembers what was delivered. Use a different name per schedule.",
            "default": "douyin-monitor"
          },
          "maxVideosPerProfile": {
            "title": "Max videos per creator",
            "minimum": 0,
            "type": "integer",
            "description": "Newest videos per creator by publish date (a pinned video counts at its own date). Douyin shows signed-out visitors the first page of a creator's videos only (44, its pinned videos included), so a larger number returns those 44 and the status message names that ceiling. 0 = profile row only.",
            "default": 20
          },
          "maxTopicsPerBoard": {
            "title": "Max topics per board",
            "minimum": 1,
            "maximum": 60,
            "type": "integer",
            "description": "Topics per board (each board lists about 50; the hot board adds ~5 trending events).",
            "default": 60
          },
          "maxItems": {
            "title": "Max rows in total",
            "minimum": 0,
            "maximum": 1000000,
            "type": "integer",
            "description": "Stop after this many rows of any type. 0 = no limit.",
            "default": 0
          },
          "commentsOnly": {
            "title": "Comments only for video URLs",
            "type": "boolean",
            "description": "For the video URLs list: deliver only the comment / danmaku rows - no video row and no related videos. With neither Comments nor Danmaku on, it reads the comments of those video URLs only (creator and hashtag videos get none). With Danmaku on, switch Comments on too to keep the comments.",
            "default": false
          },
          "compact": {
            "title": "Compact output",
            "type": "boolean",
            "description": "Core fields only, trimmed for AI / MCP pipelines.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Douyin answers the actor's own IP; a proxy is optional.",
            "default": {
              "useApifyProxy": false
            }
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Video URLs fetched in parallel.",
            "default": 4
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}