BrowsableTikTok APIs
TikTok video
Fetch public metadata, stats, media, music, hashtags, and author data for a TikTok video.
POST
/v1/tiktok/videoSend Authorization: Bearer YOUR_API_KEY. Get an API key →
Parameters
Send these fields in a flat JSON body. Add _run to choose execution options.
Provide at least one of: url; username + video_id.
urlstringOptionalFull public TikTok video URL. Minimum length: 1. Maximum length: 2000.
usernamestringOptionalTikTok username, with or without the leading @. Minimum length: 1. Maximum length: 2000.
video_idstringOptionalTikTok numeric video id. Use with username when url is not provided.
Response
Every response describes a run. Read result once run_status is succeeded.
run_id- The run to track. Keep it when contacting support.
run_status- Queued, running, waiting for sign-in, succeeded, or failed. Check this even after an HTTP 200.
status_url- Poll this URL while the run is pending. Keep the same run instead of starting another request.
result- The endpoint’s returned data. The example is illustrative; actual fields may be empty or unavailable.
error- On failure, inspect its code, message, retryable and action fields.
View the complete output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"success",
"video"
],
"properties": {
"video": {
"type": "object",
"required": [
"id",
"url",
"description",
"created_at",
"create_time",
"duration",
"region",
"author",
"stats",
"music",
"hashtags",
"mentions",
"media",
"subtitles"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"media": {
"type": "object",
"required": [
"cover_url",
"dynamic_cover_url",
"origin_cover_url",
"play_url",
"download_url",
"width",
"height",
"duration",
"format",
"ratio",
"definition"
],
"properties": {
"ratio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"height": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"duration": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"play_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cover_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"definition": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"origin_cover_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"dynamic_cover_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"music": {
"type": "object",
"required": [
"id",
"title",
"author_name",
"duration",
"original",
"play_url",
"cover_url"
],
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"duration": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"original": {
"type": "boolean"
},
"play_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cover_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"author_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"stats": {
"type": "object",
"required": [
"play_count",
"like_count",
"comment_count",
"share_count",
"collect_count",
"repost_count"
],
"properties": {
"like_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"play_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"share_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"repost_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"collect_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"comment_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"author": {
"type": "object",
"required": [
"id",
"username",
"display_name",
"verified",
"avatar_url",
"profile_url",
"followers",
"following",
"likes",
"video_count"
],
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"likes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"verified": {
"type": "boolean"
},
"followers": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"following": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"profile_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"video_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"duration": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"hashtags": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title"
],
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"mentions": {
"type": "array",
"items": {
"type": "object",
"required": [
"username",
"user_id",
"sec_uid"
],
"properties": {
"sec_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"subtitles": {
"type": "array",
"items": {
"type": "object",
"required": [
"language",
"language_code",
"url",
"format",
"source"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"language_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"create_time": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}View a polled run response
{
"run_id": "00000000-0000-4000-8000-000000000001",
"task_key": "tiktok-video",
"task_name": "TikTok video",
"run_status": "succeeded",
"status_url": "/v1/runs/00000000-0000-4000-8000-000000000001",
"result": {
"video": {
"id": "id-1",
"url": "https://example.com/item-1",
"media": {
"ratio": "sample",
"width": 1.5,
"format": "sample",
"height": 1.5,
"duration": 1.5,
"play_url": "https://example.com/item-1",
"cover_url": "https://example.com/item-1",
"definition": "sample",
"download_url": "https://example.com/item-1",
"origin_cover_url": "https://example.com/item-1",
"dynamic_cover_url": "https://example.com/item-1"
},
"music": {
"id": "id-1",
"title": "Stylish Shoreditch Loft with Balcony",
"duration": 1.5,
"original": true,
"play_url": "https://example.com/item-1",
"cover_url": "https://example.com/item-1",
"author_name": "Stylish Shoreditch Loft with Balcony"
},
"stats": {
"like_count": 1,
"play_count": 1,
"share_count": 1,
"repost_count": 1,
"collect_count": 1,
"comment_count": 1
},
"author": {
"id": "id-1",
"likes": 1.5,
"username": "Stylish Shoreditch Loft with Balcony",
"verified": true,
"followers": 1.5,
"following": 1.5,
"avatar_url": "https://images.example.com/avatar_url-1.jpg",
"profile_url": "https://example.com/item-1",
"video_count": 1,
"display_name": "Stylish Shoreditch Loft with Balcony"
},
"region": "London",
"duration": 1.5,
"hashtags": [
{
"id": "id-1",
"title": "Stylish Shoreditch Loft with Balcony"
}
],
"mentions": [
{
"sec_uid": "id-1",
"user_id": "user_1",
"username": "Stylish Shoreditch Loft with Balcony"
}
],
"subtitles": [
{
"url": "https://example.com/item-1",
"format": "sample",
"source": "sample",
"language": "sample",
"language_code": "sample"
}
],
"created_at": "2026-06-14T15:30:00Z",
"create_time": 1.5,
"description": "Sample description 1"
},
"success": true
},
"error": null
}Errors & retries
400Fix the fields listed inerrorsbefore retrying.428Connect the requested website account using the returned sign-in link.429Wait for the duration inRetry-After.5xxRetry transient failures with backoff. Keep the request ID.
A failed run has its own error inside the response. Retry it only when error.retryable is true.
More examples
Async request with polling
RUN=$(curl -s -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/tiktok/video" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.tiktok.com/@tiktok/video/7641647587056962846"}')
RUN_ID=$(echo "$RUN" | jq -er '.run_id // empty') || { echo "$RUN" >&2; exit 1; }
POLL_DELAY=3
while true; do
RESULT=$(curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/runs/$RUN_ID")
STATUS=$(echo "$RESULT" | jq -r '.run_status')
if [[ "$STATUS" =~ ^(succeeded|failed|errored|cancelled|canceled|expired)$ ]]; then
echo "$RESULT"
break
fi
sleep "$(awk "BEGIN { print $POLL_DELAY * (0.9 + ($RANDOM % 21) / 100) }")"
POLL_DELAY=$((POLL_DELAY < 30 ? POLL_DELAY * 2 : 30))
[ "$POLL_DELAY" -gt 30 ] && POLL_DELAY=30
doneWait-for-results request
curl -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/tiktok/video" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.tiktok.com/@tiktok/video/7641647587056962846","_run":{"async":false}}'Canonical & compatibility routes
You can also send the same JSON body to /v1/tasks/tiktok-video/runs.