> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Video Detail
> Full metadata for a single TikTok video or photo slideshow.
Pass the author's `username` to skip the internal oEmbed author lookup for a faster, cheaper fetch.
Each request costs **5 credits**. Failed requests are not charged.
## Downloading video media
Fetch video detail immediately before downloading. When available,
`video.video.media_headers` contains the anonymous CDN headers that must accompany
**that same response's** `play_addr` or `download_addr`. Do not mix a URL from a list
response with headers from video detail. No TikTok account or login cookie is needed.
```python theme={null}
media = response["video"]["video"]
headers = media.get("media_headers")
if headers:
download = requests.get(media["play_addr"], headers=headers, stream=True, timeout=30)
download.raise_for_status()
```
The headers contain a short-lived guest media cookie, not your ScrapeBadger API key.
Send them only to the returned TikTok media URL. Do not send your ScrapeBadger key
to the CDN. Refresh video detail if the link expires. If `media_headers` is null,
metadata is available but authorized media resolution was not obtained; do not treat
this as a verified downloadable link. Photo slideshows may have no video media.
Social-list requests accept count up to 50, but TikTok permits at most 30 per
upstream page. A response may contain fewer rows; follow its returned cursor.
## OpenAPI
````yaml GET /v1/tiktok/videos/{video_id}
openapi: 3.1.0
info:
title: ScrapeBadger TikTok API
version: 1.0.0
description: >-
TikTok scraping API for user profiles, videos, comments, transcripts,
hashtags, music/sounds, search, trending, and the EU Commercial Content (ad
transparency) library. Returns clean structured JSON; handles signing,
anti-bot bypass, and regional proxy routing automatically.
servers:
- url: https://scrapebadger.com
description: Production
security:
- apiKeyAuth: []
paths:
/v1/tiktok/videos/{video_id}:
get:
tags:
- TikTok Videos
summary: Get Video Detail
description: Full metadata for a single TikTok video or photo slideshow.
operationId: getTikTokVideo
parameters:
- name: video_id
in: path
required: true
schema:
type: string
description: The numeric TikTok video/aweme id.
- name: region
in: query
schema:
type: string
default: US
description: >-
Content region (ISO 3166-1 alpha-2). Routes the request through a
proxy and signer for that locale.
- name: username
in: query
schema:
type: string
description: >-
Author @handle. When supplied, skips the oEmbed author lookup for a
faster, cheaper fetch.
responses:
'200':
description: Video detail
content:
application/json:
schema:
$ref: '#/components/schemas/VideoResponse'
example:
video:
id: '7234567890123456789'
description: 'new dance #fyp #dance'
create_time_utc: 1700000000
create_time_at: '2023-11-14T22:13:20Z'
region: US
url: >-
https://www.tiktok.com/@charlidamelio/video/7234567890123456789
share_url: >-
https://www.tiktok.com/@charlidamelio/video/7234567890123456789
aweme_type: 0
author:
id: '6784129854561813509'
sec_uid: MS4wLjABAAAA...
unique_id: charlidamelio
nickname: charli d'amelio
avatar_thumb: https://p16-sign.tiktokcdn-us.com/avatar.jpeg
signature: no bio yet
verified: true
follower_count: 155600000
following_count: 1300
heart_count: 11800000000
video_count: 2700
region: US
music:
id: '7011111111111111111'
title: original sound
author_name: charli d'amelio
duration: 15
play_url: https://sf16-sg.tiktokcdn.com/music.mp3
original: true
stats:
play_count: 24000000
digg_count: 3100000
comment_count: 18000
share_count: 42000
collect_count: 99000
video:
height: 1024
width: 576
duration: 15
ratio: 540p
format: mp4
cover: https://p16-sign.tiktokcdn-us.com/cover.jpeg
play_addr: https://v16-webapp.tiktok.com/video.mp4
download_addr: https://v16-webapp.tiktok.com/download.mp4
has_watermark: true
hashtags:
- fyp
- dance
mentions: []
challenges:
- id: '229207'
title: fyp
desc: ''
is_commerce: false
is_slideshow: false
image_urls: []
is_ad: false
is_pinned: false
region: US
components:
schemas:
VideoResponse:
type: object
properties:
video:
$ref: '#/components/schemas/TikTokVideo'
region:
type: string
required:
- video
- region
TikTokVideo:
type: object
properties:
id:
type: string
description:
type: string
description: Caption text.
text_language:
type: string
create_time_utc:
type: integer
description: Post Unix timestamp.
create_time_at:
type: string
description: Post ISO 8601 UTC.
region:
type: string
description: Location created.
url:
type: string
description: Web video URL.
share_url:
type: string
description: Canonical share link.
group_id:
type: string
aweme_type:
type: integer
description: 0 video, 150 photo/slideshow, ...
content_type:
type: string
author:
$ref: '#/components/schemas/TikTokAuthor'
music:
$ref: '#/components/schemas/TikTokMusic'
stats:
$ref: '#/components/schemas/TikTokStats'
video:
$ref: '#/components/schemas/TikTokVideoMeta'
status:
$ref: '#/components/schemas/TikTokVideoStatus'
video_control:
$ref: '#/components/schemas/TikTokVideoControl'
anchors:
type: array
items:
$ref: '#/components/schemas/TikTokAnchor'
hashtags:
type: array
items:
type: string
mentions:
type: array
items:
type: string
text_extra:
type: array
items:
$ref: '#/components/schemas/TikTokTextExtra'
challenges:
type: array
items:
$ref: '#/components/schemas/TikTokChallenge'
effect_stickers:
type: array
items:
$ref: '#/components/schemas/TikTokEffectSticker'
is_slideshow:
type: boolean
image_urls:
type: array
items:
type: string
description: Image URLs for photo/slideshow posts.
is_ad:
type: boolean
is_aigc:
type: boolean
aigc_description:
type: string
is_pinned:
type: boolean
is_muted:
type: boolean
secret:
type: boolean
private_item:
type: boolean
duet_enabled:
type: boolean
stitch_enabled:
type: boolean
share_enabled:
type: boolean
comment_status:
type: string
can_repost:
type: boolean
is_paid_content:
type: boolean
is_on_this_day:
type: boolean
support_danmaku:
type: boolean
description: Supports bullet comments.
subtitles:
type: array
items:
$ref: '#/components/schemas/TikTokSubtitle'
description: Populated only on the transcript endpoint.
voice_to_text:
type: string
description: ASR transcript (transcript endpoint only).
diversification_labels:
type: array
items:
type: string
suggested_words:
type: array
items:
type: string
required:
- id
description: A TikTok post (video or photo slideshow) with full metadata.
TikTokAuthor:
type: object
properties:
id:
type: string
description: Numeric user id.
sec_uid:
type: string
description: Secure user id (sec_uid) used for downstream list calls.
unique_id:
type: string
description: The @handle.
nickname:
type: string
description: Display name.
avatar_thumb:
type: string
avatar_medium:
type: string
avatar_larger:
type: string
signature:
type: string
description: Bio text.
verified:
type: boolean
private_account:
type: boolean
follower_count:
type: integer
following_count:
type: integer
heart_count:
type: integer
description: Total likes received.
video_count:
type: integer
digg_count:
type: integer
description: Likes given.
region:
type: string
verify_reason:
type: string
verification_type:
type: integer
account_region:
type: string
language:
type: string
original_musician:
type: boolean
is_star:
type: boolean
ins_id:
type: string
description: Linked Instagram handle.
twitter_name:
type: string
youtube_channel_title:
type: string
room_id:
type: string
description: Non-empty while the user is live.
commerce_user_level:
type: integer
with_shop_entry:
type: boolean
description: Author summary embedded in a video, comment, or search result.
TikTokMusic:
type: object
properties:
id:
type: string
title:
type: string
author_name:
type: string
album:
type: string
duration:
type: integer
description: Seconds.
play_url:
type: string
cover_thumb:
type: string
cover_medium:
type: string
cover_large:
type: string
original:
type: boolean
is_copyrighted:
type: boolean
mid:
type: string
owner_id:
type: string
owner_nickname:
type: string
is_commerce_music:
type: boolean
is_original_sound:
type: boolean
video_count:
type: integer
description: Videos using this sound (standalone music endpoints only).
user_count:
type: integer
description: >-
Distinct creators using this sound (standalone music endpoints
only).
description: Sound/music attached to a video, or a standalone music entity.
TikTokStats:
type: object
properties:
play_count:
type: integer
description: Views.
digg_count:
type: integer
description: Likes.
comment_count:
type: integer
share_count:
type: integer
collect_count:
type: integer
description: Saves/bookmarks.
download_count:
type: integer
forward_count:
type: integer
whatsapp_share_count:
type: integer
repost_count:
type: integer
description: Engagement statistics for a video.
TikTokVideoMeta:
type: object
properties:
height:
type: integer
width:
type: integer
duration:
type: integer
description: Seconds.
ratio:
type: string
format:
type: string
definition:
type: string
codec_type:
type: string
encoded_type:
type: string
bitrate:
type: integer
cover:
type: string
origin_cover:
type: string
dynamic_cover:
type: string
animated_cover:
type: string
ai_dynamic_cover:
type: string
share_cover:
type: string
play_addr:
type: string
description: Direct play URL.
download_addr:
type: string
description: Watermarked download URL.
download_no_watermark_addr:
type: string
description: Clean MP4 (mobile).
has_watermark:
type: boolean
volume_loudness:
type: number
volume_peak:
type: number
description: Playable-media metadata for a video.
TikTokVideoStatus:
type: object
properties:
is_delete:
type: boolean
allow_share:
type: boolean
allow_comment:
type: boolean
private_status:
type: integer
description: 0 public, 1 friends, 2 private.
in_reviewing:
type: boolean
reviewed:
type: boolean
is_prohibited:
type: boolean
download_status:
type: integer
self_see:
type: boolean
description: Moderation/availability state of a post.
TikTokVideoControl:
type: object
properties:
allow_download:
type: boolean
allow_duet:
type: boolean
allow_stitch:
type: boolean
allow_react:
type: boolean
allow_comment:
type: boolean
share_type:
type: integer
prevent_download:
type: boolean
description: Per-post interaction permissions.
TikTokAnchor:
type: object
properties:
id:
type: string
type:
type: integer
keyword:
type: string
url:
type: string
icon:
type: string
description: A link/shopping/POI anchor attached to a post.
TikTokTextExtra:
type: object
properties:
type:
type: string
description: '''hashtag'' or ''mention''.'
hashtag_name:
type: string
user_unique_id:
type: string
user_id:
type: string
start:
type: integer
end:
type: integer
description: An entity (hashtag or @mention) inside the caption.
TikTokChallenge:
type: object
properties:
id:
type: string
title:
type: string
description: Hashtag text, no '#'.
desc:
type: string
cover:
type: string
is_commerce:
type: boolean
description: A hashtag/challenge referenced from a video.
TikTokEffectSticker:
type: object
properties:
id:
type: string
name:
type: string
photo_url:
type: string
description: An effect/sticker applied to a video.
TikTokSubtitle:
type: object
properties:
language:
type: string
language_code:
type: string
url:
type: string
source:
type: string
description: ASR vs creator.
version:
type: string
format:
type: string
description: A subtitle/caption track for a video.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.