FetchFox
Get started

TikTok video metrics API

Retrieve a single public TikTok video’s metrics and available metadata. Use this operation when you already know the video URL and need a fresh observation for your application.

Try with free creditsRead as Markdown

Make a request

GET /tiktok/stats accepts query parameters. POST /tiktok/stats accepts the same inputs as JSON. Send your project key in the x-access-key header; keep it on your server.

Credits: 1 credit per successful request.

curl request example
curl
curl --fail-with-body --get 'https://api.fetchfox.net/tiktok/stats' \
  -H 'x-access-key: YOUR_KEY' \
  --data-urlencode 'url=https://www.tiktok.com/@example/video/VIDEO_ID'
JavaScript request example
JavaScript
// Run on your server with FETCHFOX_API_KEY set.
const url = new URL('https://api.fetchfox.net/tiktok/stats');
url.searchParams.set('url', 'https://www.tiktok.com/@example/video/VIDEO_ID');
const response = await fetch(url, {
  headers: { 'x-access-key': process.env.FETCHFOX_API_KEY },
  signal: AbortSignal.timeout(130000)
});
if (!response.ok) throw new Error('HTTP ' + response.status);
const result = await response.json();
if (!result.success) throw new Error('Request unsuccessful');
console.log(result.data);
Python request example
Python
import json, os
from urllib.parse import urlencode
from urllib.request import Request, urlopen

query = urlencode({"url":"https://www.tiktok.com/@example/video/VIDEO_ID"})
request = Request('https://api.fetchfox.net/tiktok/stats?' + query,
    headers={'x-access-key': os.environ['FETCHFOX_API_KEY']})
with urlopen(request, timeout=130) as response:
    result = json.load(response)
if not result.get('success'):
    raise RuntimeError('Request unsuccessful')
print(result['data'])

Replace placeholder source IDs with real public URLs. See limits and retries before automating calls.

Consistent video fields

TikTok video stats, search results and channel videos expose durationSeconds as a number, thumbnailUrl, and publishedAt as an ISO 8601 timestamp. Unavailable canonical values are null. Legacy duration, thumbnail and createTime fields remain for existing clients; use the canonical fields for new integrations.

Use a complete video URL

Pass the full public video URL in url. The request authenticates with your project’s x-access-key header. This endpoint reads one item; use keyword search for discovery or channel videos for a known creator’s recent publications.

Turn metrics into a time series

Keep the source URL and a retrieval timestamp for every successful observation. Public counts can change independently of your polling schedule, and missing fields should remain missing in your storage.

Choose a polling interval that fits your credit allowance and request limits. FetchFox supplies observations; it does not schedule your jobs or send monitoring alerts.

Handle platform restrictions

Private, deleted, region-restricted, or temporarily inaccessible videos can fail. Inspect the status and error payload; retry transient failures only within a bounded budget. The current operation does not provide comment text, transcripts, or downloadable video files.

Continue building