TikTok Explore Feed Trending Post Scraper

{
  "description": "Collect the public TikTok Explore feed with no login or cookies. All=120 is the default; 123 is accepted as a legacy alias. Optional country selection, filters, only-new monitoring, transcript text, post-detail enrichment and Key-Value Store media rehosting are additive.",
  "properties": {
    "autoDiscoverCategories": {
      "default": false,
      "description": "When true, an empty or All-only selection expands to all 21 verified Explore categories. If specific categories are selected, the missing categories are appended.",
      "prefill": false,
      "title": "Auto-Discover All Categories",
      "type": "boolean"
    },
    "categories": {
      "default": [
        "All"
      ],
      "description": "Categories to collect. Accepts names, numeric IDs, or legacy {id,name} objects. All=120; topics 100-119: Anime & Comics, Shows, Beauty Care, Games, Comedy, Daily Life, Family, Relationship, Drama, Outfit, Lipsync, Food, Sports, Animals, Society, Cars, Education, Fitness & Health, Technology, Singing & Dancing. 123 is accepted as a legacy alias for All. 121/122 (empty upstream) and 124+ (invalid upstream) are skipped with a warning.",
      "editor": "json",
      "prefill": [
        "All"
      ],
      "title": "Categories",
      "type": "array"
    },
    "categoryId": {
      "description": "Legacy shorthand for one category. It replaces the categories list. 100-120 are accepted; 123 maps to 120; other values are skipped with a warning.",
      "maximum": 100000,
      "minimum": 1,
      "title": "Category ID (legacy shorthand)",
      "type": "integer"
    },
    "countries": {
      "default": [],
      "description": "Optional ISO 3166-1 alpha-2 markets. Empty means the actor's current egress and no proxy. Each selected country uses a per-country Apify proxy (AUTO first, residential only after a proven block). The feed follows the egress IP, not a query parameter.",
      "editor": "stringList",
      "items": {
        "pattern": "^[A-Za-z]{2}$",
        "type": "string"
      },
      "maxItems": 10,
      "prefill": [],
      "title": "Countries / Markets",
      "type": "array"
    },
    "country": {
      "default": "",
      "description": "Single-country shorthand. Ignored when countries is non-empty.",
      "editor": "textfield",
      "pattern": "^([A-Za-z]{2})?$",
      "title": "Country (shorthand)",
      "type": "string"
    },
    "includePostDetails": {
      "default": false,
      "description": "Fetch the public post detail page for each selected post (bounded to the emitted maxItems) and merge locationCreated plus poi/imagePost when the feed omitted them. Detail requests are fail-soft: a 403, stub page or parse failure keeps the original post. Adds one page request per emitted row.",
      "prefill": false,
      "title": "Include Post Details",
      "type": "boolean"
    },
    "includeTranscripts": {
      "default": false,
      "description": "Fetch subtitle WebVTT URLs and add subtitles[].text. Subtitle metadata is always returned when available; text is opt-in and fail-soft.",
      "prefill": false,
      "title": "Include Transcript Text",
      "type": "boolean"
    },
    "maxItems": {
      "description": "Legacy alias for maxItemsPerCategory. It is used when maxItemsPerCategory is absent or exactly the default 3; an explicitly non-default maxItemsPerCategory wins.",
      "maximum": 1000,
      "minimum": 1,
      "title": "Max Items (legacy alias)",
      "type": "integer"
    },
    "maxItemsPerCategory": {
      "default": 3,
      "description": "Hard cap on emitted posts per category. The cap is applied before any page is pushed, so a 30-item page never overshoots. The default is 3 because media rehosting is on by default and adds one browser page plus several HTTP media fetches per emitted post.",
      "maximum": 1000,
      "minimum": 1,
      "prefill": 3,
      "title": "Max Items Per Category",
      "type": "integer"
    },
    "minComments": {
      "default": 0,
      "description": "Drop posts with fewer comments. Missing stats fail a positive threshold.",
      "maximum": 1000000000000,
      "minimum": 0,
      "prefill": 0,
      "title": "Minimum Comments",
      "type": "integer"
    },
    "minLikes": {
      "default": 0,
      "description": "Drop posts with fewer likes. Missing stats fail a positive threshold.",
      "maximum": 1000000000000,
      "minimum": 0,
      "prefill": 0,
      "title": "Minimum Likes",
      "type": "integer"
    },
    "minShares": {
      "default": 0,
      "description": "Drop posts with fewer shares. Missing stats fail a positive threshold.",
      "maximum": 1000000000000,
      "minimum": 0,
      "prefill": 0,
      "title": "Minimum Shares",
      "type": "integer"
    },
    "minViews": {
      "default": 0,
      "description": "Drop posts with fewer playCount views. Missing stats fail a positive threshold.",
      "maximum": 1000000000000,
      "minimum": 0,
      "prefill": 0,
      "title": "Minimum Views",
      "type": "integer"
    },
    "onlyNew": {
      "default": false,
      "description": "Emit only posts that were not present in the named state store. State is read and written only when this is true.",
      "prefill": false,
      "title": "Only New Posts",
      "type": "boolean"
    },
    "postedWithin": {
      "default": "any",
      "description": "Client-side filter on createTime relative to the run start.",
      "enum": [
        "any",
        "24h",
        "7d",
        "30d",
        "90d"
      ],
      "prefill": "any",
      "title": "Posted Within",
      "type": "string"
    },
    "rehostVideo": {
      "default": true,
      "description": "Open each emitted post with Playwright to capture the real video/mp4 response, then HTTP-fetch the signed cover, originCover, dynamicCover, zoomCover, avatar, music, slideshow image and subtitle files. Every captured payload is stored in the run's default key-value store and the original signed URL is kept as a <field>Original value plus in mediaSources. video.playUrl and video.downloadUrl use tiktok-video-{postId}.mp4; other media use typed tiktok-{kind}-{postId}-... keys. Rehosting is fail-soft per field and never drops a post. It adds one browser page plus several media fetches per emitted record and increases run time and KV storage use; keep maxItemsPerCategory small.",
      "prefill": false,
      "title": "Rehost Media in Key-Value Store",
      "type": "boolean"
    },
    "stateKey": {
      "default": "",
      "description": "Optional key-value store key for onlyNew. When empty, a deterministic key is derived from categories, countries and filters.",
      "editor": "textfield",
      "maxLength": 200,
      "title": "Only-New State Key",
      "type": "string"
    }
  },
  "required": [
    "categories"
  ],
  "schemaVersion": 1,
  "title": "TikTok Explore/Trending Scraper Input",
  "type": "object"
}

{
  "actorOutputSchemaVersion": 1,
  "properties": {
    "data": {
      "description": "Dataset of Explore posts. Each row preserves the legacy feedType/categoryId/categoryName identity and adds rank, position, marketRegion, itemCategoryId/itemCategoryName, derived engagement metrics, place, adFlags, subtitles, mediaExpiresAt, provenance fields and optional KVS media rehosting fields (mediaRehosted, mediaRehostedAll, rehostStatus, rehostStatusByField, mediaRehostedFields, mediaSources, and per-field <field>Original values).",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "Trending Post Data",
      "type": "string"
    }
  },
  "title": "TikTok Explore Feed Trending Post Scraper Output"
}

{
  "actorSpecification": 1,
  "fields": {
    "adFlags": {
      "description": "adAuthorization, brandOrganicType, adLabelVersion, aigcLabelType, moderationAigcLabelType and isAiGenerated; empty subkeys are omitted",
      "title": "Ad / AI Flags",
      "type": "object"
    },
    "ageHours": {
      "description": "(run start - createTime) / 3600, 2 decimals",
      "title": "Age Hours",
      "type": "number"
    },
    "author": {
      "description": "Author profile snapshot; includes commentSetting, duetSetting, stitchSetting, downloadSetting and isEmbedBanned when present. avatarUrl uses a KV URL after rehosting and avatarUrlOriginal keeps the signed source.",
      "title": "Author",
      "type": "object"
    },
    "caption": {
      "description": "Post caption/description text",
      "title": "Caption",
      "type": "string"
    },
    "categoryId": {
      "description": "Requested category ID. All is 120; legacy 123 inputs are normalized to 120.",
      "title": "Category ID",
      "type": "integer"
    },
    "categoryName": {
      "description": "Canonical requested category name (e.g. All, Sports, Technology)",
      "title": "Category Name",
      "type": "string"
    },
    "collectCount": {
      "description": "Number of times post was saved/collected",
      "title": "Collect Count",
      "type": "integer"
    },
    "commentCount": {
      "description": "Number of comments",
      "title": "Comment Count",
      "type": "integer"
    },
    "createTime": {
      "description": "Unix timestamp when the post was created",
      "title": "Create Time",
      "type": "integer"
    },
    "createdAt": {
      "description": "ISO 8601 UTC timestamp of post creation",
      "title": "Created At",
      "type": "string"
    },
    "duetEnabled": {
      "description": "Whether duets are allowed on this post",
      "title": "Duet Enabled",
      "type": "boolean"
    },
    "engagementRate": {
      "description": "(likes + comments + shares + collects) / plays, 6 decimals. Omitted when playCount is zero or missing.",
      "title": "Engagement Rate",
      "type": "number"
    },
    "feedType": {
      "description": "Always 'explore' for rows from this actor",
      "title": "Feed Type",
      "type": "string"
    },
    "firstSeen": {
      "description": "Present only for onlyNew runs: ISO timestamp when the post first entered the state store",
      "title": "First Seen",
      "type": "string"
    },
    "hashtags": {
      "description": "Hashtags used in the post",
      "title": "Hashtags",
      "type": "array"
    },
    "images": {
      "description": "Slideshow images for photo posts (postType='slideshow'). With rehosting, urlList becomes a single KV image URL and urlListOriginal keeps the signed candidate list.",
      "title": "Images",
      "type": "array"
    },
    "isAd": {
      "description": "Whether the post is marked as an advertisement",
      "title": "Is Ad",
      "type": "boolean"
    },
    "isNew": {
      "description": "Present only for onlyNew runs; true for posts emitted during this run",
      "title": "Is New",
      "type": "boolean"
    },
    "itemCategoryId": {
      "description": "The item's own CategoryType. Explore feeds are mixed, so this can differ from categoryId.",
      "title": "Item Category ID",
      "type": "integer"
    },
    "itemCategoryName": {
      "description": "Canonical name for itemCategoryId",
      "title": "Item Category Name",
      "type": "string"
    },
    "lastSeen": {
      "description": "Present only for onlyNew runs: ISO timestamp for this observation",
      "title": "Last Seen",
      "type": "string"
    },
    "likeCount": {
      "description": "Number of likes (from statsV2)",
      "title": "Like Count",
      "type": "integer"
    },
    "locationCreated": {
      "description": "Declared for backward compatibility. The Explore item payload does not contain it; it is emitted only when includePostDetails=true and the post detail page supplies a value.",
      "title": "Location Created (legacy)",
      "type": "string"
    },
    "marketRegion": {
      "description": "Selected ISO country, or the actual region detected from the Explore page state when no country was requested. Never guessed.",
      "title": "Market Region",
      "type": "string"
    },
    "mediaExpiresAt": {
      "description": "Per-asset ISO 8601 expiries: video, cover, avatar, music, subtitles",
      "title": "Media Expiries",
      "type": "object"
    },
    "mediaRehosted": {
      "description": "True when the video bytes were stored in the default Key-Value Store, or, for a post without video, when at least one other signed media field was stored. False when no media field succeeded; the original signed URLs remain.",
      "title": "Media Rehosted",
      "type": "boolean"
    },
    "mediaRehostedAll": {
      "description": "True when every attempted media field was stored in the Key-Value Store. False when any field failed or was skipped.",
      "title": "All Media Rehosted",
      "type": "boolean"
    },
    "mediaRehostedFields": {
      "description": "Boolean per-field success map derived from rehostStatusByField.",
      "title": "Media Rehosted Fields",
      "type": "object"
    },
    "mediaSources": {
      "description": "Original signed URL or URL list for every rehosted field. Rehosted fields also keep a matching <field>Original value.",
      "title": "Media Sources",
      "type": "object"
    },
    "mediaUrlExpiresAt": {
      "description": "Earliest ISO 8601 UTC expiry across the original signed video, cover, avatar, music and subtitle URLs. It remains the source expiry after rehosting; KV URLs do not use it.",
      "title": "Media URL Expires At",
      "type": "string"
    },
    "mentions": {
      "description": "@mentions in the caption",
      "title": "Mentions",
      "type": "array"
    },
    "music": {
      "description": "Sound/music used in the post (id, title, authorName, duration, album, playUrl, coverUrl). After rehosting, playUrl and coverUrl use KV URLs and playUrlOriginal/coverUrlOriginal keep the signed sources.",
      "title": "Music",
      "type": "object"
    },
    "place": {
      "description": "POI object when present: id, name, address, city, province, country, countryCode, category, typeName. No latitude/longitude is invented.",
      "title": "Place / POI",
      "type": "object"
    },
    "playCount": {
      "description": "Number of video plays",
      "title": "Play Count",
      "type": "integer"
    },
    "playsPerHour": {
      "description": "playCount / ageHours, 1 decimal. Omitted when ageHours is not positive.",
      "title": "Plays Per Hour",
      "type": "number"
    },
    "position": {
      "description": "0-based emitted order within the market/category after filters and dedupe",
      "title": "Position",
      "type": "integer"
    },
    "postId": {
      "description": "Unique TikTok post/video ID (string)",
      "title": "Post ID",
      "type": "string"
    },
    "postType": {
      "description": "Either 'video' or 'slideshow'",
      "title": "Post Type",
      "type": "string"
    },
    "postUrl": {
      "description": "Direct URL to the TikTok post",
      "title": "Post URL",
      "type": "string"
    },
    "rank": {
      "description": "1-based emitted order within the market/category after filters and dedupe",
      "title": "Rank",
      "type": "integer"
    },
    "recordType": {
      "description": "Always 'explorePost'",
      "title": "Record Type",
      "type": "string"
    },
    "rehostStatus": {
      "description": "Record-level outcome: ok, partial, no_media_fields, no_post_url, missing_post_id, no_video_response, navigation_failed, playwright_unavailable, browser_unavailable, body_unavailable, empty_body, invalid_content_type, not_mp4, not_vtt, http_<status>, network_error, capture_error, kv_error, or kv_url_error. Failures keep the original URLs and never drop the record.",
      "title": "Rehost Status",
      "type": "string"
    },
    "rehostStatusByField": {
      "description": "Per-field status keyed by output path, for example video.playUrl, video.cover, video.zoomCover.240, music.playUrl, author.avatarUrl, images[0].urlList and subtitles[0].url. Values are ok or a fail-soft status.",
      "title": "Rehost Status By Field",
      "type": "object"
    },
    "repostCount": {
      "description": "Number of reposts",
      "title": "Repost Count",
      "type": "integer"
    },
    "scrapedAt": {
      "description": "ISO 8601 UTC timestamp of the run start",
      "title": "Scraped At",
      "type": "string"
    },
    "shareCount": {
      "description": "Number of shares",
      "title": "Share Count",
      "type": "integer"
    },
    "shareEnabled": {
      "description": "Whether sharing is enabled on this post",
      "title": "Share Enabled",
      "type": "boolean"
    },
    "sourceUrl": {
      "description": "Provenance alias for postUrl",
      "title": "Source URL",
      "type": "string"
    },
    "stitchEnabled": {
      "description": "Whether stitching is allowed on this post",
      "title": "Stitch Enabled",
      "type": "boolean"
    },
    "subtitles": {
      "description": "Subtitle metadata from subtitleInfos, or video.claInfo.captionInfos when subtitleInfos is absent. text is added only with includeTranscripts=true. With rehosting, url is a KV VTT URL and urlOriginal keeps the signed source.",
      "title": "Subtitles",
      "type": "array"
    },
    "textLanguage": {
      "description": "Language code of the caption",
      "title": "Text Language",
      "type": "string"
    },
    "video": {
      "description": "Video metadata. With rehostVideo=true, playUrl, downloadUrl, cover, originCover, dynamicCover and zoomCover are stable Key-Value Store URLs, each with a matching <field>Original value and a mediaSources entry. sourcePlayUrl keeps the original signed play URL, and sourceDownloadUrl keeps a distinct signed download URL. Without rehosting, playUrl prefers the working www.tiktok.com/aweme/v1/play/ carrier and downloadUrl falls back to it.",
      "title": "Video",
      "type": "object"
    }
  },
  "title": "TikTok Explore/Trending Scraper Dataset",
  "views": {
    "overview": {
      "display": {
        "component": "table",
        "properties": {
          "ageHours": {
            "format": "number",
            "label": "Age (hours)"
          },
          "caption": {
            "format": "text",
            "label": "Caption"
          },
          "categoryId": {
            "format": "number",
            "label": "Category ID"
          },
          "categoryName": {
            "format": "text",
            "label": "Category"
          },
          "createdAt": {
            "format": "text",
            "label": "Created At"
          },
          "engagementRate": {
            "format": "number",
            "label": "Engagement Rate"
          },
          "feedType": {
            "format": "text",
            "label": "Feed Type"
          },
          "itemCategoryName": {
            "format": "text",
            "label": "Item Category"
          },
          "likeCount": {
            "format": "number",
            "label": "Likes"
          },
          "marketRegion": {
            "format": "text",
            "label": "Market"
          },
          "mediaRehosted": {
            "format": "text",
            "label": "Media Rehosted"
          },
          "mediaRehostedAll": {
            "format": "text",
            "label": "All Media Rehosted"
          },
          "playCount": {
            "format": "number",
            "label": "Plays"
          },
          "playsPerHour": {
            "format": "number",
            "label": "Plays / Hour"
          },
          "postId": {
            "format": "text",
            "label": "Post ID"
          },
          "postUrl": {
            "format": "link",
            "label": "Post URL"
          },
          "rank": {
            "format": "number",
            "label": "Rank"
          },
          "rehostStatus": {
            "format": "text",
            "label": "Rehost Status"
          }
        }
      },
      "title": "Overview",
      "transformation": {
        "fields": [
          "rank",
          "marketRegion",
          "categoryName",
          "categoryId",
          "itemCategoryName",
          "feedType",
          "postId",
          "caption",
          "playCount",
          "likeCount",
          "engagementRate",
          "ageHours",
          "playsPerHour",
          "createdAt",
          "postUrl",
          "mediaRehosted",
          "mediaRehostedAll",
          "rehostStatus"
        ]
      }
    }
  }
}