# 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.

Canonical: https://fetchfox.net/docs/tiktok-video-stats-api

## Request

GET /tiktok/stats (query parameters) or POST /tiktok/stats (JSON). Authenticate with x-access-key. Keep keys server-side.

Credits: 1 credit per successful request.

### 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

```
// 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

```
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'])
```

## 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.

## Related pages

- https://fetchfox.net/docs/tiktok-channel-videos-api

- https://fetchfox.net/docs/tiktok-search-api

- https://fetchfox.net/guides/tiktok-keyword-monitoring