TopTik — TikTok data

Resolve a TikTok @handle to the account's numeric uid and sec_uid. Start here: every tiktok_creator_* tool takes the sec_uid this returns. An empty user_list means no exact match was found.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "The @handle, with or without the leading @."
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "handle"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A creator's profile: handle, nickname, bio, follower, following and video counts, privacy and verification flags, and avatar.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^(MS4w[A-Za-z0-9_-]{20,}|\\d{6,25})$",
      "description": "sec_uid (MS4w…) or numeric uid, from tiktok_resolve_username."
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A creator's posts, newest first, with stats. Page by passing the previous response's max_cursor as cursor until has_more is 0. Pinned posts appear on page one only.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^(MS4w[A-Za-z0-9_-]{20,}|\\d{6,25})$",
      "description": "sec_uid (MS4w…) or numeric uid."
    },
    "count": {
      "description": "Posts per page. (1-35, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 35
    },
    "cursor": {
      "description": "max_cursor from the previous page. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Videos a creator has liked. Only works when the account keeps its likes public; most do not, and a private list returns no videos.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^MS4w[A-Za-z0-9_-]{20,}$",
      "description": "sec_uid (MS4w…). A numeric uid is not accepted here."
    },
    "count": {
      "description": "Videos per page. (1-35, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 35
    },
    "cursor": {
      "description": "max_cursor from the previous page. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A sample of a creator's followers (most recent), plus the total. One page only: TikTok does not page this list reliably, so this is a sample and not an export.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^(MS4w[A-Za-z0-9_-]{20,}|\\d{6,25})$",
      "description": "sec_uid (MS4w…) or numeric uid."
    },
    "count": {
      "description": "Followers to return. (1-50, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A sample of the accounts a creator follows, plus the total. One page only, for the same reason as followers.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^(MS4w[A-Za-z0-9_-]{20,}|\\d{6,25})$",
      "description": "sec_uid (MS4w…) or numeric uid."
    },
    "count": {
      "description": "Accounts to return. (1-50, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A creator's playlists (TikTok calls them mixes or series). Most creators have none, which returns total 0.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^(MS4w[A-Za-z0-9_-]{20,}|\\d{6,25})$",
      "description": "sec_uid (MS4w…) or numeric uid."
    },
    "cursor": {
      "description": "cursor from the previous page. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One video or photo post by id: caption, plays, likes, comments, shares, saves, duration, hashtags, sound and author.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{6,25}$",
      "description": "The numeric video id — the digits after /video/ in a TikTok link."
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Top-level comments on a video, with like and reply counts. cursor is an offset: pass the previous response's cursor to continue. TikTok re-ranks between pages, so dedupe on comment_id.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{6,25}$",
      "description": "The numeric video id."
    },
    "count": {
      "description": "Comments per page. (1-50, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "cursor": {
      "description": "Offset from the previous response. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Replies under one comment. Worth calling only when tiktok_video_comments reported reply_count above 0.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{6,25}$",
      "description": "The numeric video id."
    },
    "comment_id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{6,25}$",
      "description": "comment_id from tiktok_video_comments."
    },
    "count": {
      "description": "Replies per page. (1-50, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "cursor": {
      "description": "Offset from the previous response. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "comment_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Direct media URLs for one post: no-watermark video, watermarked video, audio, covers, and the images of a photo post. Links only, no bytes; they are signed and expire (see expires), so fetch promptly.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{6,25}$",
      "description": "The numeric video id."
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A video's spoken text from TikTok's own caption track: one joined string plus timed cues. has_transcript false means the video has no caption track, which is common and is not an error.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{6,25}$",
      "description": "The numeric video id."
    },
    "lang": {
      "description": "Language tag such as en or es-MX. Omit to get the original track.",
      "type": "string",
      "minLength": 1,
      "maxLength": 16,
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$"
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Sound title to music id, with the closest candidates. Feed the id to tiktok_sound_videos.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "The sound's title as TikTok shows it."
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "title"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Videos TikTok associates with a sound. Treat it as a feed seeded by the sound, not a strict filter: some results use a different sound, so check music_id on each row.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{6,25}$",
      "description": "music id from tiktok_sound_resolve or any video row."
    },
    "cursor": {
      "description": "cursor from the previous page. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Hashtag name to its id, with total video and view counts. Feed the id to tiktok_hashtag_videos.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "The hashtag, with or without #."
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Videos under a hashtag. Pages hold about 12 videos whatever count asks for; page with cursor.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\d{1,25}$",
      "description": "hashtag id from tiktok_hashtag_resolve."
    },
    "count": {
      "description": "Videos per page; TikTok caps this near 12. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "cursor": {
      "description": "cursor from the previous page. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Keyword search over videos. TikTok search is a bounded, re-ranked pool, not an endless list: ask for count 30, page with cursor, dedupe on video_id, and stop when two pages add nothing new.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Search keywords."
    },
    "count": {
      "description": "Results per page. 30 yields the most distinct results per call. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "cursor": {
      "description": "cursor from the previous page. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "sort_type": {
      "description": "0 = relevance (default), 1 = most liked. (0-3)",
      "type": "integer",
      "minimum": 0,
      "maximum": 3
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Keyword search over accounts, with follower counts. Pages by offset, not cursor. For one exact @handle use tiktok_resolve_username instead: it is cheaper and more reliable.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Search keywords."
    },
    "count": {
      "description": "Results per page. (1-30, default 10)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "offset": {
      "description": "Number of results to skip: 0, then count, then 2 x count. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Keyword search over hashtags, with post and view counts. One page only.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Search keywords."
    },
    "count": {
      "description": "Results to return. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Keyword search over sounds, with usage counts. cursor is an offset: pass the previous response's cursor.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Search keywords."
    },
    "count": {
      "description": "Results per page. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "cursor": {
      "description": "cursor from the previous page. Omit for page one. (default 0)",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Live rooms on air right now that match a keyword, with the host's account. One page only. For playable stream URLs use tiktok_live_streams.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Search keywords."
    },
    "count": {
      "description": "Rooms to return. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Keyword search over photo-mode (carousel) posts, with image URLs and stats. One page only.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Search keywords."
    },
    "count": {
      "description": "Results to return. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

TikTok's Explore / Discover feed: what is trending now. Not personalised and not cached, so each call returns a fresh set; call again for more.

{
  "type": "object",
  "properties": {
    "count": {
      "description": "Videos to return. (1-18, default 12)",
      "type": "integer",
      "minimum": 1,
      "maximum": 18
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Live rooms matching a keyword, each with playable stream URLs per quality (FLV always, HLS when TikTok provides it), title and viewer count. URLs are signed (see expires_at), but a room usually ends long before its signature does; if one quality fails, try another.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Search keywords."
    },
    "count": {
      "description": "Rooms to return. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search TikTok places (points of interest) by name: address, coordinates, rating, review count and video count.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Place name or keywords."
    },
    "count": {
      "description": "Places to return. (1-30, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "expand": {
      "description": "false (default): a compact JSON summary sized for a model's context. true: the complete, unmodified response from the data API — can exceed 500 KB for list tools, so ask for it only when a field you need is missing from the compact form. Same price either way.",
      "type": "boolean"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}