Skip to main content
POST
Get TikTok video

Description

This endpoint allows you to fetch comprehensive metadata about a specific TikTok video, including video details, author information, statistics, music, hashtag challenges, and more.

Endpoint

POST /api/v1/get-tiktok-video

Request Headers

Request Body

The url must be a valid TikTok video URL, e.g., https://www.tiktok.com/@username/video/1234567890 or https://vm.tiktok.com/ZMhKxyz/

Responses

Success (200 OK)

Returns comprehensive video information including metadata, statistics, author details, music, and challenges.
Response Headers:
  • Content-Type: application/json
  • X-RateLimit-Limit: The rate limit for the user.
  • X-RateLimit-Remaining: The remaining number of requests for the user.

Error Responses

400 Bad Request

Indicates an issue with the request parameters.
Possible error messages:
  • Invalid JSON in request body
  • 'url' parameter is required and must be a non-empty string.
  • Invalid TikTok video URL format.
  • The video service could not process the provided URL.
  • The video service reported an issue.

401 Unauthorized

API key is missing, invalid, or inactive.

403 Forbidden

API key does not have enough credits.

404 Not Found

The requested TikTok video could not be found.

500 Internal Server Error

An unexpected error occurred on the server.
Possible error messages:
  • Service not configured. Please contact support.
  • Service authentication failed. Please contact support.
  • An unexpected server error occurred...

502 Bad Gateway

Indicates an issue with an upstream service.
Possible error messages:
  • The video service is currently unavailable.
  • Received invalid data structure from video service.
  • Error fetching video data from the upstream service.

503 Service Unavailable

Rate limit exceeded with an upstream service.

Example Request

cURL

Node.js (fetch)

Notes

  • The response includes comprehensive video metadata suitable for analytics, content management, and monitoring.
  • Video statistics include views (playCount), likes (diggCount), comments, shares, and saves (collectCount).
  • The textExtra array provides detailed information about hashtags mentioned in the video description with their positions.
  • Music information is included when the video uses a soundtrack.
  • Challenge/hashtag data includes cover images and descriptions.

Credit Cost

This endpoint costs 10 credits per successful request. For more details, see our Credit Costs page.

Rate Limiting

This endpoint is subject to standard API rate limits. Check the X-RateLimit-Limit and X-RateLimit-Remaining headers in the response to monitor your usage.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
url
string<uri>
required
requestSource
enum<string>

Optional identifier describing where the API request originated.

Available options:
API,
WEB,
MAKE_DOT_COM,
ZAPIER,
N8N,
PLAYGROUND,
DEFAULT_AUTOMATION,
AGENT_PREVIEW,
AGENT_LIVE,
AUTOPILOT,
STUDIO

Response

TikTok video retrieved.

id
string
desc
string
createTime
integer | null
createTimeISO
string<date-time> | null
video
object
author
object
music
object
challenges
object[]
stats
object
textExtra
object[]