{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Scraper",
    "description": "Scrape TikTok videos, profiles, hashtags, search results, sounds and playlists. Get views, likes, shares, saves, captions, subtitles, music and full author stats, plus comments with replies and up to 10,000 followers per profile. Date filters, sorting and country are free. Fast runs.",
    "version": "0.0",
    "x-build-id": "WJoKz3B4cwmsqeHE8"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/calm_builder~tiktok-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-calm_builder-tiktok-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/calm_builder~tiktok-scraper/runs": {
      "post": {
        "operationId": "runs-sync-calm_builder-tiktok-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/calm_builder~tiktok-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-calm_builder-tiktok-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": {
          "profiles": {
            "title": "Profiles",
            "type": "array",
            "description": "TikTok usernames or profile links, one per row.\n\nSupported formats:\n- `khaby.lame`\n- `@khaby.lame`\n- `https://www.tiktok.com/@khaby.lame`\n\nEach profile is saved once as its own row with `type: \"profile\"`, and its videos are saved as separate rows that link back to it through `profileId`. Use **Profile sections** below to also collect reposts, liked videos, playlists or stories.",
            "items": {
              "type": "string"
            }
          },
          "hashtags": {
            "title": "Hashtags",
            "type": "array",
            "description": "Hashtags to collect videos from, one per row, with or without the `#`.\n\nExamples: `fitness`, `#booktok`.",
            "items": {
              "type": "string"
            }
          },
          "searchQueries": {
            "title": "Search terms",
            "type": "array",
            "description": "Keywords to search TikTok for, one per row — exactly as you would type them into the TikTok search bar.\n\nChoose what kind of results you want with **Search results type** below.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "TikTok links",
            "type": "array",
            "description": "Direct TikTok links, one per row. The Actor recognises the link type automatically.\n\nSupported links:\n- Video — `https://www.tiktok.com/@user/video/7301234567890123456`\n- Photo post — `https://www.tiktok.com/@user/photo/7301234567890123456`\n- Profile — `https://www.tiktok.com/@user`\n- Hashtag — `https://www.tiktok.com/tag/fitness`\n- Sound — `https://www.tiktok.com/music/original-sound-7301234567890123456`\n- Playlist — `https://www.tiktok.com/@user/playlist/name-7301234567890123456`\n\nShort links (`vm.tiktok.com`, `vt.tiktok.com`) work too.",
            "items": {
              "type": "string"
            }
          },
          "resultsPerPage": {
            "title": "Maximum videos per source",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "How many videos to collect from **each** profile, hashtag, search term, sound or playlist.\n\nDirect video links always return one video each, regardless of this value.\n\nSet to **0** to collect only profile details and follower lists, without videos.",
            "default": 10
          },
          "searchSection": {
            "title": "Search results type",
            "enum": [
              "videos",
              "photos",
              "creators",
              "top"
            ],
            "type": "string",
            "description": "Which TikTok search tab to collect results from. Only applies to **Search terms**.\n\n- **Videos** — matching videos\n- **Photos** — matching photo posts\n- **Creators** — matching accounts (returned as profiles)\n- **Top** — TikTok's mixed \"Top\" tab",
            "default": "videos"
          },
          "profileSections": {
            "title": "Profile sections",
            "type": "array",
            "description": "Which parts of each profile to collect. Only applies to **Profiles** and profile links.\n\n- **Videos** — the videos the account posted\n- **Reposts** — videos the account reposted\n- **Liked videos** — only visible when the account has made its likes public\n- **Playlists** — every video in the account's playlists\n- **Stories** — currently active stories\n\nSections the account keeps private are skipped and noted in the log.",
            "items": {
              "type": "string",
              "enum": [
                "videos",
                "reposts",
                "liked",
                "playlists",
                "stories"
              ],
              "enumTitles": [
                "Videos",
                "Reposts",
                "Liked videos",
                "Playlists",
                "Stories"
              ]
            },
            "default": [
              "videos"
            ]
          },
          "newerThan": {
            "title": "Only videos newer than",
            "type": "string",
            "description": "Skip videos posted before this date. Pick a date, or enter a relative period such as `7 days` or `3 months`.\n\nFor profiles, the Actor jumps straight to this date range instead of scrolling through older videos, so filtered runs finish faster."
          },
          "olderThan": {
            "title": "Only videos older than",
            "type": "string",
            "description": "Skip videos posted after this date. Combine with **Only videos newer than** to collect a specific period."
          },
          "minViews": {
            "title": "Minimum views",
            "minimum": 0,
            "type": "integer",
            "description": "Only return videos with at least this many views. Leave empty to keep all videos."
          },
          "minLikes": {
            "title": "Minimum likes",
            "minimum": 0,
            "type": "integer",
            "description": "Only return videos with at least this many likes. Leave empty to keep all videos."
          },
          "sortBy": {
            "title": "Sort videos by",
            "enum": [
              "default",
              "newest",
              "oldest",
              "mostViewed",
              "mostLiked",
              "mostShared"
            ],
            "type": "string",
            "description": "Order of the videos collected from each source.\n\n- **Default** — the order TikTok shows them in\n- **Newest first** / **Oldest first** — by upload date\n- **Most viewed** / **Most liked** / **Most shared** — by engagement\n\nSorting applies to the videos collected from each source, up to your **Maximum videos per source**.",
            "default": "default"
          },
          "excludePinnedPosts": {
            "title": "Skip pinned videos",
            "type": "boolean",
            "description": "Leave out the videos a creator pinned to the top of their profile, so results follow the real upload order.",
            "default": false
          },
          "includeComments": {
            "title": "Include comments ($)",
            "type": "boolean",
            "description": "Collect the comments of every video in the run. They are saved in the **Comments & replies** table, one row each, linked to their video through `videoId`.\n\nComments are an optional add-on with their own price. Comment order and comment filters below are included at no extra cost.",
            "default": false
          },
          "maxCommentsPerVideo": {
            "title": "Maximum comments per video",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "How many top-level comments to collect from each video.",
            "default": 20
          },
          "includeReplies": {
            "title": "Include replies to comments ($)",
            "type": "boolean",
            "description": "Also collect replies to each comment.\n\nRequires **Include comments**. Each reply is charged as a comment.",
            "default": false
          },
          "maxRepliesPerComment": {
            "title": "Maximum replies per comment",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many replies to collect under each comment.",
            "default": 10
          },
          "commentLayout": {
            "title": "Comments layout",
            "enum": [
              "rows",
              "threads"
            ],
            "type": "string",
            "description": "How comments are saved in the **Comments & replies** table.\n\n- **One row each** — every comment and every reply is its own row, with `type` and `parentCommentId`; best for spreadsheets\n- **Replies nested** — one row per comment, with its replies inside the `replies` field; best for JSON and code\n\nEvery row carries `videoId`, `videoUrl`, `videoAuthor` and `videoCaption`. Pricing is the same either way.",
            "default": "rows"
          },
          "commentSort": {
            "title": "Comment order",
            "enum": [
              "default",
              "mostLiked",
              "newest"
            ],
            "type": "string",
            "description": "Which comments to collect first.\n\n- **TikTok's order** — the order the TikTok app shows (fastest)\n- **Most liked** — the most-liked comments of each video\n- **Newest** — the most recent comments of each video\n\n**Most liked** and **Newest** read up to 1,000 comments per video to pick from, so they take a few seconds longer per video. You are charged only for the comments returned.",
            "default": "default"
          },
          "commentsNewerThan": {
            "title": "Only comments newer than",
            "type": "string",
            "description": "Skip comments posted before this date. Pick a date, or enter a relative period such as `24 hours` or `7 days`. Ideal for monitoring."
          },
          "minCommentLikes": {
            "title": "Minimum comment likes",
            "minimum": 0,
            "type": "integer",
            "description": "Only return comments with at least this many likes. Leave empty to keep all."
          },
          "commentKeywords": {
            "title": "Comment must contain",
            "type": "array",
            "description": "Only return comments containing at least one of these words or phrases (not case-sensitive), e.g. `price`, `where to buy`. Leave empty to keep all.",
            "items": {
              "type": "string"
            }
          },
          "includeFollowers": {
            "title": "Include followers ($)",
            "type": "boolean",
            "description": "Collect the accounts that follow each profile in the run.\n\nFollower lists are an optional add-on with their own price.",
            "default": false
          },
          "includeFollowing": {
            "title": "Include following ($)",
            "type": "boolean",
            "description": "Collect the accounts each profile follows.\n\nSome accounts hide this list. When that happens the profile is marked as private in the log and nothing is charged.",
            "default": false
          },
          "maxFollowersPerProfile": {
            "title": "Maximum accounts per list",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "How many followers (and, separately, how many followed accounts) to collect for each profile.",
            "default": 100
          },
          "includeSubtitles": {
            "title": "Include subtitles",
            "type": "boolean",
            "description": "Add the full subtitle text of each video in the `subtitles` field, in every language TikTok provides. Included at no extra cost.\n\nOnly videos that have subtitles on TikTok (including auto-generated captions) return them.",
            "default": false
          },
          "country": {
            "title": "Scrape as if from",
            "enum": [
              "US",
              "AR",
              "AU",
              "BD",
              "BR",
              "CA",
              "CO",
              "EG",
              "FR",
              "DE",
              "ID",
              "IT",
              "JP",
              "MY",
              "MX",
              "NL",
              "NG",
              "PK",
              "PH",
              "PL",
              "SA",
              "ZA",
              "KR",
              "ES",
              "SE",
              "TH",
              "TR",
              "AE",
              "GB",
              "VN"
            ],
            "type": "string",
            "description": "Collect results as TikTok shows them in this country. This affects which search, hashtag and sound results you get. Included at no extra cost.\n\nThe default, **United States**, gives the most complete results. If a country has nothing for a source, the Actor tries United States for it automatically.",
            "default": "US"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}