{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Video Search Scraper - Metrics & Filters",
    "description": "Search TikTok videos by keyword or hashtag and get views, likes, comments, shares, engagement rate, duration, hashtags and creator data. Filter by minimum views, likes, or duration. Cookieless, provider-backed, MCP-ready.",
    "version": "0.1",
    "x-build-id": "NGt7Y9Wxf0kHWIFbu"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~tiktok-video-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-tiktok-video-search-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/khadinakbar~tiktok-video-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-tiktok-video-search-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/khadinakbar~tiktok-video-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-tiktok-video-search-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": {
          "searchQueries": {
            "title": "Search keywords",
            "type": "array",
            "description": "One or more keywords to search TikTok videos for, e.g. 'protein recipe' or 'nike running'. Each keyword runs its own paginated video search. Provide keywords here OR hashtags in the Hashtags field (at least one is needed). Plain text only — this is NOT a TikTok URL, username, or video link.",
            "items": {
              "type": "string"
            }
          },
          "hashtags": {
            "title": "Hashtags",
            "type": "array",
            "description": "Optional TikTok hashtags to pull the video feed for, with or without the leading '#', e.g. 'running' or '#fitness'. Each hashtag runs its own paginated video search alongside any keywords. Leave empty to search by keyword only.",
            "items": {
              "type": "string"
            }
          },
          "maxResultsPerQuery": {
            "title": "Max videos per query",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum videos to return and charge for per keyword or hashtag. Ranges 1–10000, defaults to 50. The actor paginates until it hits this cap or runs out of videos. Applies independently to each query.",
            "default": 50
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "relevance",
              "most-liked",
              "date-posted"
            ],
            "type": "string",
            "description": "Ordering for keyword searches: 'relevance' (TikTok default), 'most-liked' (highest engagement first), or 'date-posted' (newest first). Defaults to 'relevance'. Ignored for hashtag feeds, which return TikTok's native hashtag order.",
            "default": "relevance"
          },
          "datePosted": {
            "title": "Date posted",
            "enum": [
              "yesterday",
              "this-week",
              "this-month",
              "last-3-months",
              "last-6-months",
              "all-time"
            ],
            "type": "string",
            "description": "Restrict keyword searches to videos posted within a recent window: yesterday, this week, this month, the last 3 or 6 months, or all time. Defaults to 'all-time'. Applies to keyword searches only.",
            "default": "all-time"
          },
          "region": {
            "title": "Region",
            "type": "string",
            "description": "Two-letter ISO country code used to localize results, e.g. 'US', 'GB', or 'DE'. Defaults to 'US'. Changes which regional results TikTok surfaces for the same keyword.",
            "default": "US"
          },
          "minPlays": {
            "title": "Minimum views (plays)",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos with at least this many plays/views, e.g. 100000 to surface viral content. Defaults to 0 (no filter). Applied after fetching, so filtered-out videos are never charged. Videos missing a play count are dropped when this is set.",
            "default": 0
          },
          "minLikes": {
            "title": "Minimum likes",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos with at least this many likes, e.g. 5000. Defaults to 0 (no filter). Applied after fetching; filtered-out videos are not charged.",
            "default": 0
          },
          "minComments": {
            "title": "Minimum comments",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos with at least this many comments, e.g. 500. Defaults to 0 (no filter). Applied after fetching; filtered-out videos are not charged.",
            "default": 0
          },
          "minShares": {
            "title": "Minimum shares",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos with at least this many shares, e.g. 200. Defaults to 0 (no filter). Applied after fetching; filtered-out videos are not charged.",
            "default": 0
          },
          "minDurationSeconds": {
            "title": "Minimum duration (seconds)",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos at least this many seconds long, e.g. 15 to skip very short clips. Defaults to 0 (no filter). Videos missing a duration are dropped when this is set.",
            "default": 0
          },
          "maxDurationSeconds": {
            "title": "Maximum duration (seconds)",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep videos no longer than this many seconds, e.g. 60 to focus on short-form. Defaults to 0 (no limit). Videos missing a duration are dropped when this is set.",
            "default": 0
          },
          "includePhotoPosts": {
            "title": "Include photo posts",
            "type": "boolean",
            "description": "TikTok search returns image carousel posts alongside videos. Keep true to include them, or set false to keep video posts only. Defaults to true.",
            "default": true
          },
          "maxPagesPerQuery": {
            "title": "Max pages per query",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Safety cap on how many provider pages to fetch per query before stopping, even if the result cap is not reached. Ranges 1–500, defaults to 20. Raise it only for very large result caps on sparse queries.",
            "default": 20
          },
          "providerOrder": {
            "title": "Data provider",
            "enum": [
              "scrapecreators-first",
              "sociavault-first",
              "scrapecreators-only",
              "sociavault-only"
            ],
            "type": "string",
            "description": "Which backend data provider to use. 'scrapecreators-first' tries ScrapeCreators then SociaVault (default); the other options force or reverse the order. Both providers return public TikTok video data with no cookies required.",
            "default": "scrapecreators-first"
          },
          "includeRawData": {
            "title": "Include raw provider data",
            "type": "boolean",
            "description": "Attach the raw, unnormalized provider payload to each row under 'rawResult' for debugging. Defaults to false to keep rows compact and cheap for AI agents to read.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}