{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Hashtag Scraper - Videos, Views & Tag Analytics",
    "description": "Scrape TikTok hashtags: every video posted under a tag with its caption, author, views, likes, comments and shares, plus the tag's own total views and video count. Filter by date and likes, sort, and download the videos and covers.",
    "version": "0.1",
    "x-build-id": "8xoPOdsEbbv5xGKyn"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/s-r~tiktok-hashtag-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-s-r-tiktok-hashtag-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/s-r~tiktok-hashtag-scraper/runs": {
      "post": {
        "operationId": "runs-sync-s-r-tiktok-hashtag-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/s-r~tiktok-hashtag-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-s-r-tiktok-hashtag-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",
        "required": [
          "hashtags"
        ],
        "properties": {
          "hashtags": {
            "title": "Hashtags",
            "type": "array",
            "description": "One per line. The leading # is optional and a full https://www.tiktok.com/tag/... link works too, so 'coffee', '#coffee' and the link are the same tag.",
            "items": {
              "type": "string"
            }
          },
          "maxVideosPerHashtag": {
            "title": "Maximum videos per hashtag",
            "minimum": 0,
            "maximum": 400,
            "type": "integer",
            "description": "TikTok serves roughly 200 unique videos per tag before it stops, so asking for more returns what exists. Set it to 0 to collect only the reach figures.",
            "default": 60
          },
          "includeHashtagStats": {
            "title": "Include the hashtag's reach figures",
            "type": "boolean",
            "description": "Adds one row per tag with its total views and how many videos carry it. Free: it is a single extra request per tag.",
            "default": true
          },
          "resultsPerPage": {
            "title": "Results per request",
            "minimum": 1,
            "maximum": 30,
            "type": "integer",
            "description": "How many videos to ask for per request, up to 30. Lower means more requests for the same total.",
            "default": 30
          },
          "sortBy": {
            "title": "Order the results",
            "enum": [
              "relevance",
              "most_liked",
              "most_viewed",
              "most_commented",
              "most_shared",
              "newest",
              "oldest"
            ],
            "type": "string",
            "description": "Applied to the rows this run collected, not to TikTok's feed order. 'Relevance' keeps TikTok's own ordering untouched.",
            "default": "relevance"
          },
          "oldestPostDate": {
            "title": "Posted on or after",
            "type": "string",
            "description": "YYYY-MM-DD, a full ISO timestamp, or a relative window such as '7 days' or '3 months'. Filtering happens after the fetch, so a narrow window reads more pages and returns fewer rows."
          },
          "newestPostDate": {
            "title": "Posted on or before",
            "type": "string",
            "description": "Same formats as the field above."
          },
          "leastDiggs": {
            "title": "Minimum likes",
            "minimum": 0,
            "type": "integer",
            "description": "Drop videos with fewer likes than this."
          },
          "mostDiggs": {
            "title": "Maximum likes",
            "minimum": 0,
            "type": "integer",
            "description": "Drop videos with more likes than this. Useful for finding small accounts rather than the same viral posts."
          },
          "excludeAds": {
            "title": "Exclude paid posts",
            "type": "boolean",
            "description": "Drop rows TikTok marks as advertising.",
            "default": false
          },
          "scrapeAdditionalAuthorMeta": {
            "title": "Extra author fields",
            "type": "boolean",
            "description": "Adds the author's bio, avatar, region, following count and total likes. Free: the fields are already in the response.",
            "default": false
          },
          "shouldDownloadVideos": {
            "title": "Download the videos",
            "type": "boolean",
            "description": "Stores the MP4 in the run's key-value store and puts a public link on the row. TikTok's raw media links return 403 to anyone who pastes them elsewhere, which is why downloading is the only way to get a link that works.",
            "default": false
          },
          "shouldDownloadCovers": {
            "title": "Download the thumbnails",
            "type": "boolean",
            "description": "Stores each video's thumbnail in the key-value store and puts a public link on the row.",
            "default": false
          },
          "shouldDownloadAvatars": {
            "title": "Download the author avatars",
            "type": "boolean",
            "description": "Stores the author's or account's profile picture and puts a public link on the row.",
            "default": false
          },
          "shouldDownloadMusicCovers": {
            "title": "Download the sound covers",
            "type": "boolean",
            "description": "Stores the artwork of the sound used in the video.",
            "default": false
          },
          "shouldDownloadSlideshowImages": {
            "title": "Download slideshow images",
            "type": "boolean",
            "description": "Photo posts have no video at all. This stores each image instead.",
            "default": false
          },
          "maxMediaDownloads": {
            "title": "Maximum files to download",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "A ceiling across every download option, so a large search cannot turn into a large bill by accident.",
            "default": 50
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "Two-letter country code sent with the request. TikTok serves follower lists regionally, so this can change the ordering.",
            "default": "us"
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Two-letter language code for the search.",
            "default": "en"
          },
          "proxyCountryCode": {
            "title": "Search from this country",
            "type": "string",
            "description": "Two-letter code for where the request should appear to come from. Leave empty to use the default route. Setting the country above changes what TikTok ranks; setting this changes where the request arrives from, and the two are worth matching."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}