> ## Documentation Index > Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt > Use this file to discover all available pages before exploring further. # Video > Scrapes a single public TikTok video (or photo post) by URL (`tiktok.com/@user/video/`). Returns the description, created date, language, the country it was posted from, TikTok’s content categories and related searches, stats (views, likes, comments, shares, saves, reposts — TikTok rounds large view/like/comment/share counts; saves are exact), the author (bio, avatar, created date, verified/private/seller flags, stats, interaction settings), video details (duration, size, covers, play/download URLs, every rendition, subtitles) or photo-post images, music (with its TikTok sound page and Apple Music / Spotify links when TikTok matches the sound to a song), hashtags, mentions, tagged place, effects, stickers, link anchors, AI-generated labels and flags. **Downloading the video file:** TikTok only serves `video.video.playUrl`, `downloadUrl` and `formats[].url` to requests that send the `Cookie` and `Referer` headers returned in `mediaHeaders` (without them: 403 Access Denied), so these links do not open when pasted into a browser. Send both headers from your code, e.g. `curl -H "Cookie: " -H "Referer: " "" -o video.mp4`. Covers, photo-post images, music and subtitles need no headers. Media URLs expire within hours. **Watermarks:** `playUrl` and every `formats[].url` are watermark-free; `downloadUrl` is TikTok’s download copy with the TikTok logo and @username burned in. **Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free. Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button). ```text Prompt I want to make an API call to /v1/tiktok/video. Here are the details: Endpoint: GET https://api.scraperize.com/v1/tiktok/video Description: Scrapes a single public TikTok video (or photo post) by URL (`tiktok.com/@user/video/`). Returns the description, created date, language, the country it was posted from, TikTok’s content categories and related searches, stats (views, likes, comments, shares, saves, reposts — TikTok rounds large view/like/comment/share counts; saves are exact), the author (bio, avatar, created date, verified/private/seller flags, stats, interaction settings), video details (duration, size, covers, play/download URLs, every rendition, subtitles) or photo-post images, music (with its TikTok sound page and Apple Music / Spotify links when TikTok matches the sound to a song), hashtags, mentions, tagged place, effects, stickers, link anchors, AI-generated labels and flags. Required Headers: - x-api-key: Your API key Parameters: - url (string) [required]: The TikTok video URL, e.g. https://www.tiktok.com/@user/video/7689399654345182471 (a photo post’s /photo/ link works too). - cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh. Example Response: { "data": { "video": { "id": "7689399654345182471", "url": "https://www.tiktok.com/@brainjotter/video/7689399654345182471", "type": "video", "description": "Tag that friend woth 1% social battery", "createdAt": "2026-09-25T09:18:00.000Z", "language": "en", "stats": { "playCount": 350300, "likeCount": 75100, "commentCount": 821, "shareCount": 1474, "collectCount": 3609, "repostCount": 0 }, "author": { "id": "6810285179828945926", "secUid": "MS4wLjABAAAA1E4wyGvJvdI8bl-5URa446ywZys3NQzvXvLB64kmRgwSjkn9E-wd2LGuKReZXXxm", "handle": "brainjotter", "nickname": "SUPREME GREEN👑", "bio": "Promocode : JOTTERS TO GET 300% b0nus", "avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/dbac796bf5becb428bf361070bddc211~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=14579&refresh_token=84aabd4…", "verified": true, "privateAccount": false, "stats": { "followerCount": 12100000, "followingCount": 5144, "likeCount": 159200000, "videoCount": 611, "friendCount": 0, "diggCount": 905 }, "createdAt": "2020-04-03T03:39:51.000Z", "liveRoomId": null, "ttSeller": false, "settings": { "comment": 0, "duet": 0, "stitch": 0, "download": 0 } }, "video": { "duration": 109, "width": 576, "height": 1024, "definition": "540p", "format": "mp4", "codec": "h264", "bitrate": 305033, "quality": "lowest", "size": 4170004, "coverUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oA78PbVNBPIiai2EYIYAuoIG2IWBTzCArsBFP~tplv-tiktokx-origin.image?dr=14575&x-expires=1791381600&x-signature…", "originCoverUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/ogbjMQA2BdVDwfIKACYeRoX6AbB9eD8HbKAbhB~tplv-tiktokx-origin.image?dr=14575&x-expires=1791381600&x-signatur…", "dynamicCoverUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oIANAIPjAiIF6Tb2IaBoYVP8XE7rAY2yBiCIG~tplv-tiktokx-origin.image?dr=14575&x-expires=1791381600&x-signature…", "playUrl": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/oQQ8Rgoj6ItHuLGYDPALIbMfgeebVBICgAhtYA/?a=1988&bti=ODszNWYuMDE6&&bt=297&ft=I~da4onxD1…", "downloadUrl": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/ogVwoeYuBCIgHALjtDYRgVTAkbIbA0ebTheGIg/?a=1988&bti=ODszNWYuMDE6&&bt=688&eid=20480&ft=…", "volume": { "loudness": -18, "peak": 0.54954 }, "formats": [ { "gearName": "adapt_lowest_1080_1", "qualityType": 2, "codec": "h265_hvc1", "format": "mp4", "bitrate": 607083, "fps": 25, "width": 1080, "height": 1920, "size": 8299285, "url": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/oIwHCEri98BIIo7ibaQ6Ap2GPwA2iEVYaIYPB/?a=1988&bti=ODszNWYuMDE6&&bt=592&ft=I~da4onxD12…" } ], "subtitles": [ { "language": "eng-US", "languageCode": "en", "format": "webvtt", "isAutoGenerated": true, "url": "https://v16-webapp.tiktok.com/f1f2f9e68ce9cf013eb1f16124fc05af/6ac65b3e/video/tos/alisg/tos-alisg-pv-0037/3d1330d4d4df4b9ebb2b39fc95f07bce/?a=1988&bti=ODszNWYuM…", "expiresAt": "2026-10-07T14:46:22.000Z" } ] }, "photo": null, "music": { "id": "7689399747121515272", "title": "original sound", "url": "https://www.tiktok.com/music/original-sound-7689399747121515272", "authorName": "SUPREME GREEN👑", "album": null, "duration": 109, "preciseDuration": 109.40081, "shootDuration": 109, "original": true, "isCopyrighted": false, "isCommerceMusic": true, "isUnlimitedMusic": false, "isPrivate": false, "coverUrl": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/dbac796bf5becb428bf361070bddc211~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=14579&refresh_token=84aabd4…", "playUrl": "https://v16m.tiktokcdn.com/7a06db407e731d8dcdaf14d229edc99a/6ac509be/video/tos/alisg/tos-alisg-v-27dcd7/okC2IYQiABFUbAaEAAVSqE78vPilC6lVAbrZY/?a=1233&bti=ODszNW…", "streaming": [] }, "hashtags": [], "mentions": [], "effects": [], "stickerTexts": [], "location": null, "contentCategory": { "id": 104, "name": "Comedy" }, "anchors": [], "warnings": [], "playlistId": null, "isAd": false, "isPinned": false, "isPrivate": false, "isCommerce": false, "aigcDescription": null, "aigcLabelType": null, "duetEnabled": true, "stitchEnabled": true, "shareEnabled": true, "canRepost": true, "commentStatus": 0, "region": "BR", "regionName": "Brazil", "categories": [ "Scripted Comedy" ], "suggestedSearches": [ "brainjotter" ], "isAigc": false }, "mediaHeaders": { "Cookie": "tt_chain_token=", "Referer": "https://www.tiktok.com/" }, "fetchedAt": "2026-10-05T14:44:34.839Z" }, "meta": { "requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f", "creditsCharged": 1, "creditsRemaining": 4999, "cached": false } } Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices. ``` ## OpenAPI ````yaml /api-reference/openapi.json get /v1/tiktok/video openapi: 3.0.3 info: title: Scraperize API version: 1.0.0 description: >- Extract public data from social media platforms as clean JSON. Endpoints are split by platform and by what they return, e.g. `GET /v1/twitter/tweet`. ## Authentication Send your API key in the `x-api-key` header (or `Authorization: Bearer `). Create keys in your dashboard. ## Credits Each successful live scrape costs **1 credit**. Credits are prepaid and never expire. ## Caching Every endpoint accepts an optional `cache_max_age` (`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for **0 credits**. ## Responses Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return `{ "error": { "code", "message", "requestId" } }` with a matching HTTP status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`, `cached`, and (on a hit) `cachedAt`. ## Rate limits Requests are limited per team per minute; over the limit returns `429` with a `Retry-After` header. servers: - url: https://api.scraperize.com description: Production security: - ApiKeyAuth: [] tags: - name: Twitter description: Twitter / X scraping endpoints - name: Facebook description: Facebook scraping endpoints - name: Linkme description: Linkme (link.me) scraping endpoints - name: Amazon description: Amazon (creator shop / storefront) scraping endpoints - name: Linkbio description: Linkbio (lnk.bio) scraping endpoints - name: Pillar description: Pillar (pillar.io) scraping endpoints - name: Komi description: Komi (komi.io) scraping endpoints - name: Linktree description: Linktree (linktr.ee) scraping endpoints - name: Kick description: Kick (kick.com) scraping endpoints - name: Snapchat description: Snapchat (snapchat.com) scraping endpoints - name: Telegram description: Telegram (t.me) scraping endpoints - name: LinkedIn description: LinkedIn scraping endpoints - name: Twitch description: Twitch scraping endpoints - name: TikTok description: TikTok (tiktok.com) scraping endpoints paths: /v1/tiktok/video: get: tags: - TikTok summary: Video description: >- Scrapes a single public TikTok video (or photo post) by URL (`tiktok.com/@user/video/`). Returns the description, created date, language, the country it was posted from, TikTok’s content categories and related searches, stats (views, likes, comments, shares, saves, reposts — TikTok rounds large view/like/comment/share counts; saves are exact), the author (bio, avatar, created date, verified/private/seller flags, stats, interaction settings), video details (duration, size, covers, play/download URLs, every rendition, subtitles) or photo-post images, music (with its TikTok sound page and Apple Music / Spotify links when TikTok matches the sound to a song), hashtags, mentions, tagged place, effects, stickers, link anchors, AI-generated labels and flags. **Downloading the video file:** TikTok only serves `video.video.playUrl`, `downloadUrl` and `formats[].url` to requests that send the `Cookie` and `Referer` headers returned in `mediaHeaders` (without them: 403 Access Denied), so these links do not open when pasted into a browser. Send both headers from your code, e.g. `curl -H "Cookie: " -H "Referer: " "" -o video.mp4`. Covers, photo-post images, music and subtitles need no headers. Media URLs expire within hours. **Watermarks:** `playUrl` and every `formats[].url` are watermark-free; `downloadUrl` is TikTok’s download copy with the TikTok logo and @username burned in. parameters: - name: url in: query required: true description: >- The TikTok video URL, e.g. https://www.tiktok.com/@user/video/7689399654345182471 (a photo post’s /photo/ link works too). schema: type: string example: https://www.tiktok.com/@brainjotter/video/7689399654345182471 - name: cache_max_age in: query required: false description: >- Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh. schema: type: string enum: - 1d - 3d - 7d - 14d - 30d example: 7d responses: '200': description: The TikTok video. content: application/json: schema: type: object properties: data: type: object properties: video: type: object mediaHeaders: type: object nullable: true description: >- Send these headers when downloading the video file (playUrl / downloadUrl / formats[].url); TikTok returns 403 without them. Null for photo posts. properties: Cookie: type: string Referer: type: string fetchedAt: type: string format: date-time meta: type: object description: >- requestId + credit/caching metadata (creditsCharged, creditsRemaining, cached, cachedAt). required: - data - meta example: data: video: id: '7689399654345182471' url: >- https://www.tiktok.com/@brainjotter/video/7689399654345182471 type: video description: Tag that friend woth 1% social battery createdAt: '2026-09-25T09:18:00.000Z' language: en stats: playCount: 350300 likeCount: 75100 commentCount: 821 shareCount: 1474 collectCount: 3609 repostCount: 0 author: id: '6810285179828945926' secUid: >- MS4wLjABAAAA1E4wyGvJvdI8bl-5URa446ywZys3NQzvXvLB64kmRgwSjkn9E-wd2LGuKReZXXxm handle: brainjotter nickname: SUPREME GREEN👑 bio: 'Promocode : JOTTERS TO GET 300% b0nus' avatarUrl: >- https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/dbac796bf5becb428bf361070bddc211~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=14579&refresh_token=84aabd42&x-expires=1791381600&x-signature=ACPvJDtZEAv0geFi4DcAadbGU6I%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my2 verified: true privateAccount: false stats: followerCount: 12100000 followingCount: 5144 likeCount: 159200000 videoCount: 611 friendCount: 0 diggCount: 905 createdAt: '2020-04-03T03:39:51.000Z' liveRoomId: null ttSeller: false settings: comment: 0 duet: 0 stitch: 0 download: 0 video: duration: 109 width: 576 height: 1024 definition: 540p format: mp4 codec: h264 bitrate: 305033 quality: lowest size: 4170004 coverUrl: >- https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oA78PbVNBPIiai2EYIYAuoIG2IWBTzCArsBFP~tplv-tiktokx-origin.image?dr=14575&x-expires=1791381600&x-signature=hvKMkNKzx1IMmpZFRKLZiaSz2%2Fw%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2 originCoverUrl: >- https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/ogbjMQA2BdVDwfIKACYeRoX6AbB9eD8HbKAbhB~tplv-tiktokx-origin.image?dr=14575&x-expires=1791381600&x-signature=Z9d4uXgF%2FkyBOwaDO4w3gilOFX0%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2 dynamicCoverUrl: >- https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oIANAIPjAiIF6Tb2IaBoYVP8XE7rAY2yBiCIG~tplv-tiktokx-origin.image?dr=14575&x-expires=1791381600&x-signature=c9dmAGSeLeHjH82LjUh%2Fa%2F75AuA%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2 playUrl: >- https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/oQQ8Rgoj6ItHuLGYDPALIbMfgeebVBICgAhtYA/?a=1988&bti=ODszNWYuMDE6&&bt=297&ft=I~da4onxD12Nv0De0zIxR4ESQlBF-UjNSCopiX&mime_type=video_mp4&rc=aWQzNmhpNjU3aWhlOjdmOEBpMzV1dHU5cjs2ZDMzODczNEAyLV5jLWE2Nl8xLWEzX182YSMxYC1hMmQ0bG9hLS1kMTFzcw%3D%3D&expire=1791384382&l=20261005224433739FD3832540599DFDD7&ply_type=2&policy=2&signature=7dfc86f58a70c68a8676c13608ce90c6&tk=tt_chain_token&btag=e00050000 downloadUrl: >- https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/ogVwoeYuBCIgHALjtDYRgVTAkbIbA0ebTheGIg/?a=1988&bti=ODszNWYuMDE6&&bt=688&eid=20480&ft=I~da4onxD12Nv0De0zIxR4ESQlBF-UjNSCopiX&mime_type=video_mp4&rc=NDZnMzpkPDlkOjVoZTY5PEBpMzV1dHU5cjs2ZDMzODczNEBeYy80NWAzX2ExMGJiMjNiYSMxYC1hMmQ0bG9hLS1kMTFzcw%3D%3D&expire=1791384382&l=20261005224433739FD3832540599DFDD7&ply_type=2&policy=2&signature=c62356b9f5b148b506ee768b8e51ee1d&tk=tt_chain_token&btag=e00050000 volume: loudness: -18 peak: 0.54954 formats: - gearName: adapt_lowest_1080_1 qualityType: 2 codec: h265_hvc1 format: mp4 bitrate: 607083 fps: 25 width: 1080 height: 1920 size: 8299285 url: >- https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/oIwHCEri98BIIo7ibaQ6Ap2GPwA2iEVYaIYPB/?a=1988&bti=ODszNWYuMDE6&&bt=592&ft=I~da4onxD12Nv0De0zIxR4ESQlBF-UjNSCopiX&mime_type=video_mp4&rc=aWQ3NGY1OWY6PGRmZGY1ZEBpMzV1dHU5cjs2ZDMzODczNEA2NmAuXjQ1XzYxMzYzMzEyYSMxYC1hMmQ0bG9hLS1kMTFzcw%3D%3D&expire=1791384382&l=20261005224433739FD3832540599DFDD7&ply_type=2&policy=2&signature=4affa62f0274623c057c6af53bd9850d&tk=tt_chain_token&btag=e00050000 - gearName: adapt_lower_720_1 qualityType: 14 codec: h265_hvc1 format: mp4 bitrate: 459582 fps: 25 width: 720 height: 1280 size: 6282838 url: >- https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/ooIjbiR2texgeuGYCAegLuAoAhgIsXABDHbVPI/?a=1988&bti=ODszNWYuMDE6&&bt=448&ft=I~da4onxD12Nv0De0zIxR4ESQlBF-UjNSCopiX&mime_type=video_mp4&rc=PGlkNjtnNTk1NzxoaTM5OUBpMzV1dHU5cjs2ZDMzODczNEAvLjMyMS41NWExM2IwMDJeYSMxYC1hMmQ0bG9hLS1kMTFzcw%3D%3D&expire=1791384382&l=20261005224433739FD3832540599DFDD7&ply_type=2&policy=2&signature=7de5fe673c8a7fb0c8cc33026897846b&tk=tt_chain_token&btag=e00050000 - gearName: adapt_540_1 qualityType: 28 codec: h265_hvc1 format: mp4 bitrate: 404981 fps: 25 width: 576 height: 1024 size: 5536405 url: >- https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-pve-0037c001/oIIajYYj628VR0QbiiTPrEIs7GPoF2BBCAEIA/?a=1988&bti=ODszNWYuMDE6&&bt=395&ft=I~da4onxD12Nv0De0zIxR4ESQlBF-UjNSCopiX&mime_type=video_mp4&rc=ZTY8ZWZoOzw2NDxnOzRnOkBpMzV1dHU5cjs2ZDMzODczNEA1Xi9hNl4wXl4xLWIwXzU0YSMxYC1hMmQ0bG9hLS1kMTFzcw%3D%3D&expire=1791384382&l=20261005224433739FD3832540599DFDD7&ply_type=2&policy=2&signature=4fc05196bf9551a808a9f5ade5e9d47c&tk=tt_chain_token&btag=e00050000 subtitles: - language: eng-US languageCode: en format: webvtt isAutoGenerated: true url: >- https://v16-webapp.tiktok.com/f1f2f9e68ce9cf013eb1f16124fc05af/6ac65b3e/video/tos/alisg/tos-alisg-pv-0037/3d1330d4d4df4b9ebb2b39fc95f07bce/?a=1988&bti=ODszNWYuMDE6&&bt=1058&ft=IecA0onxD12Nv0De0zIxR4ESQlBF-UjNSCopiX&mime_type=video_mp4&rc=MzV1dHU5cjs2ZDMzODczNEBpMzV1dHU5cjs2ZDMzODczNEAxYC1hMmQ0bG9hLS1kMTFzYSMxYC1hMmQ0bG9hLS1kMTFzcw%3D%3D&l=20261005224433739FD3832540599DFDD7&btag=e00050000 expiresAt: '2026-10-07T14:46:22.000Z' photo: null music: id: '7689399747121515272' title: original sound url: >- https://www.tiktok.com/music/original-sound-7689399747121515272 authorName: SUPREME GREEN👑 album: null duration: 109 preciseDuration: 109.40081 shootDuration: 109 original: true isCopyrighted: false isCommerceMusic: true isUnlimitedMusic: false isPrivate: false coverUrl: >- https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/dbac796bf5becb428bf361070bddc211~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=14579&refresh_token=84aabd42&x-expires=1791381600&x-signature=ACPvJDtZEAv0geFi4DcAadbGU6I%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my2 playUrl: >- https://v16m.tiktokcdn.com/7a06db407e731d8dcdaf14d229edc99a/6ac509be/video/tos/alisg/tos-alisg-v-27dcd7/okC2IYQiABFUbAaEAAVSqE78vPilC6lVAbrZY/?a=1233&bti=ODszNWYuMDE6&&bt=125&ft=GcDrcInz7Th-nO-GXq8Zmo&mime_type=audio_mpeg&rc=amo8NXQ5cm82ZDMzODU8NEBpamo8NXQ5cm82ZDMzODU8NEBxajI2MmRrbG9hLS1kMS1zYSNxajI2MmRrbG9hLS1kMS1zcw%3D%3D&vvpl=1&l=20261005224433739FD3832540599DFDD7&btag=e00050000&sp_exp=hash_v0 streaming: [] hashtags: [] mentions: [] effects: [] stickerTexts: [] location: null contentCategory: id: 104 name: Comedy anchors: [] warnings: [] playlistId: null isAd: false isPinned: false isPrivate: false isCommerce: false aigcDescription: null aigcLabelType: null duetEnabled: true stitchEnabled: true shareEnabled: true canRepost: true commentStatus: 0 region: BR regionName: Brazil categories: - Scripted Comedy - Comedy - Performance suggestedSearches: - brainjotter - brain jotter comedy - Apex isAigc: false mediaHeaders: Cookie: tt_chain_token= Referer: https://www.tiktok.com/ fetchedAt: '2026-10-05T14:44:34.839Z' meta: requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f creditsCharged: 1 creditsRemaining: 4999 cached: false '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: API key required — pass it in the `x-api-key` header. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '402': description: Not enough credits for this request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INSUFFICIENT_CREDITS message: >- This request costs 1 credit, but your balance is 0. Top up to continue. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '404': description: Video not found, deleted, private, or unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: >- The requested content was not found (it may not exist, be deleted, or be private). requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '422': description: Invalid query parameters (missing url, or not a TikTok video URL). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Request validation failed requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f details: - path: url message: Required '429': description: Over the per-minute rate limit — honour `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: >- Rate limit exceeded — max 100 requests per 60s. Retry in ~30s. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '503': description: >- Temporarily unavailable — retry after `Retry-After`. `error.code` tells you why: `UPSTREAM_BLOCKED` (the source blocked this request), `EXTRACTION_FAILED` (the source returned unexpected data), `PLATFORM_UNAVAILABLE` (the source is down), or `SERVICE_UNAVAILABLE` (we are at capacity). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UPSTREAM_BLOCKED message: >- The source is temporarily unavailable. Please try again shortly. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f components: schemas: Error: type: object properties: error: type: object properties: code: type: string example: NOT_FOUND message: type: string example: The requested content was not found. requestId: type: string example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f details: type: array items: type: object description: Present on validation errors. required: - code - message - requestId required: - error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your API key. Send it in the `x-api-key` header (or `Authorization: Bearer `). Create and manage keys from your dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.