{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Scraper — Hashtag Date Filter, Profiles & Search",
    "description": "Scrape TikTok profiles, hashtags, search results, and direct videos with optional MP4/cover downloads. HTTP-first extraction normally starts no browser or proxy and never uses residential IPs. $0.50 per 1,000 results, as low as $0.40 on volume tiers. A run with 0 valid rows is FAILED.",
    "version": "1.0",
    "x-build-id": "0dVbH01m1KLRCjDj2"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/funny_ground~tiktok-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-funny_ground-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/funny_ground~tiktok-scraper/runs": {
      "post": {
        "operationId": "runs-sync-funny_ground-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/funny_ground~tiktok-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-funny_ground-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",
            "uniqueItems": true,
            "type": "array",
            "description": "TikTok usernames (without @) or full profile URLs.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hashtags": {
            "title": "Hashtags",
            "uniqueItems": true,
            "type": "array",
            "description": "Hashtags without #.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hashtagPostedAfter": {
            "title": "Hashtag: posted after",
            "type": "string",
            "description": "Only return hashtag videos posted on or after this date/time (inclusive). Accepts ISO 8601 — date-only (e.g. 2026-05-01) is anchored to 00:00:00 UTC; date-time (e.g. 2026-05-01T00:00:00Z) is used as-is. Leave empty to disable. Only applies to videos from the `hashtags` input — profiles / search / direct URLs ignore this filter."
          },
          "hashtagPostedBefore": {
            "title": "Hashtag: posted before",
            "type": "string",
            "description": "Only return hashtag videos posted strictly before this date/time (exclusive). Same format as `hashtagPostedAfter`. Leave empty for no upper bound. With a date filter, `resultsPerInput` is also the candidate scan budget; set it ~3-5× the count you actually need because out-of-window candidates are discarded."
          },
          "searchKeywords": {
            "title": "Search keywords",
            "uniqueItems": true,
            "type": "array",
            "description": "Free-text search queries.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "videoUrls": {
            "title": "Video URLs",
            "uniqueItems": true,
            "type": "array",
            "description": "Direct TikTok video URLs to scrape. Exact mode returns unrounded engagement counts; Fast mode favors throughput and may return TikTok's rounded web counters.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "dataSource": {
            "title": "Data source",
            "enum": [
              "auto",
              "tikwm",
              "browser"
            ],
            "type": "string",
            "description": "Auto (recommended) tries the lightweight exact-count HTTP path for profiles, hashtags, searches, and direct videos, then starts a non-residential browser only for recoverable failures. HTTP only guarantees no browser or proxy. Browser forces the legacy fallback path.",
            "default": "auto"
          },
          "statsPrecision": {
            "title": "Engagement count precision",
            "enum": [
              "exact",
              "fast"
            ],
            "type": "string",
            "description": "Exact (recommended) uses the rate-limited detail/list source so playCount and other engagement counters are unrounded. Fast only changes direct-video URLs to parallel TikTok HTML; popular-video counters from that web payload can be rounded (for example 2,012,616 to 2,000,000).",
            "default": "exact"
          },
          "failOnPartialFailure": {
            "title": "Fail when any input is empty",
            "type": "boolean",
            "description": "If false (recommended), a run with valid rows succeeds with warnings even when some inputs are private, deleted, empty, or blocked. If true, preserve the legacy strict behavior and mark any partial result as FAILED.",
            "default": false
          },
          "resultsPerInput": {
            "title": "Results per input",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Max videos to return for each profile / hashtag / keyword. With a hashtag date filter, this is the maximum number of feed candidates scanned and the returned count may be lower. Set to 0 for unlimited (until end of feed).",
            "default": 50
          },
          "shouldDownloadVideos": {
            "title": "Download video files",
            "type": "boolean",
            "description": "If true, store video MP4 files in Apify Key-Value Store. WARNING: significantly increases cost & runtime.",
            "default": false
          },
          "shouldDownloadCovers": {
            "title": "Download cover images",
            "type": "boolean",
            "description": "If true, store video thumbnail JPGs in Apify Key-Value Store.",
            "default": false
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Country setting for profile/hashtag browser fallback on the default non-residential Apify Proxy pool. Search browser fallback uses direct container egress. Proxy groups, custom proxy URLs, and proxy disabling are ignored so this Actor never uses residential IPs."
          },
          "fallbackToResidential": {
            "title": "Legacy option: auto-fallback to RESIDENTIAL",
            "type": "boolean",
            "description": "Ignored. The actor never uses or switches to residential IPs.",
            "default": false
          },
          "blockImages": {
            "title": "Block images (saves bandwidth)",
            "type": "boolean",
            "description": "Abort image requests to cut browser bandwidth and speed up page loads. Turn off only if your target route starts returning 0 results.",
            "default": true
          },
          "headless": {
            "title": "Headless browser",
            "type": "boolean",
            "description": "Run Playwright in headless mode. Set false only when debugging locally.",
            "default": true
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 30,
            "type": "integer",
            "description": "Max simultaneous seed tasks, including fast direct-video HTTP requests and browser pages. Exact-count HTTP calls remain safely rate-limited. Higher mainly speeds browser fallback, downloads, and Fast direct mode.",
            "default": 4
          },
          "requestTimeoutSecs": {
            "title": "Request timeout (s)",
            "minimum": 10,
            "maximum": 300,
            "type": "integer",
            "description": "Page load timeout in seconds.",
            "default": 45
          },
          "maxAttemptsPerSeed": {
            "title": "Max attempts per seed",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Maximum browser attempts for each profile / hashtag / direct URL before giving up. Lower values improve speed when TikTok blocks non-residential IPs.",
            "default": 2
          },
          "maxSearchAttempts": {
            "title": "Max search attempts",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Maximum browser-fallback attempts for each search keyword after the exact HTTP path fails. Each retry now uses a fresh page/session instead of repeating on the same blocked page.",
            "default": 2
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}