> Documentation index: https://docs.scrapier.io/llms.txt
> Auth: header `X-API-Key: <key>` · Base: https://api.scrapier.io/api/v2 · Synchronous; paginate with `cursor` ← `data.next_cursor`.

# TikTok Transcript

Structured TikTok data: send `urls`. Single lookup, 1 credit per successful call.

`GET|POST https://api.scrapier.io/api/v2/tiktok-transcript/` · 1 credit per successful call · Single lookup · Long-running

## Overview

Call `GET /api/v2/tiktok-transcript/` with `urls`. The results are in `data.transcript`. 9 optional parameters refine the call (see Parameters).

## Request

```bash
curl -G "https://api.scrapier.io/api/v2/tiktok-transcript/" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "urls=https://www.tiktok.com/@natgeo/video/7683891628230315295" \
  --max-time 210
```

```python
import requests

resp = requests.get(
    "https://api.scrapier.io/api/v2/tiktok-transcript/",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"urls": "https://www.tiktok.com/@natgeo/video/7683891628230315295"},
    timeout=210,
)
body = resp.json()
if not resp.ok:
    raise RuntimeError(body.get("error") or body.get("detail"))

print(body["data"]["transcript"])
```

POST with a JSON body works too (same parameters; the body is merged over the query string).

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `X-API-Key` (header) | string | yes | — | Your API key. |
| `urls` | string | yes | e.g. `https://www.tiktok.com/@natgeo/video/7683891628230315295` | TikTok video / photo URL, vm./vt./tiktok.com/t/ short link, legacy m.tiktok.com/v/<id>.html or bare 19-digit id. Single lookup: the full record (transcript text + VTT + segments, every caption track inline, moments, post metadata) is returned under `transcript`, next_cursor is always null. |
| `cursor` | string | no | — | Pagination cursor returned in the previous response's `next_cursor`. Pass it back unchanged to fetch the next page. When `next_cursor` is null, you have reached the last page. |
| `language` | string | no | `en` | 2-letter code of the transcript wanted; falls back to the original-language track. en on a non-English video without captions is translated by Whisper. Locked in cursor. |
| `use_ai_as_fallback` | boolean | no | `true` | faster-whisper transcription for videos WITHOUT caption tracks. Locked in cursor. |
| `ai_max_duration_seconds` | integer | no | `60` | Longest video the AI fallback transcribes on default 60, hard cap 90. Longer videos without captions return transcript null + transcript_reason. Locked in cursor. |
| `transcribe_all` | boolean | no | `false` | AI-transcribe even when captions exist (captions still returned). Locked in cursor. |
| `moments` | string | no | `true` | true/all, false, or a CSV of moment kinds located on the transcript timeline. One of: `true`, `false`, `brand`, `sponsor_read`, `product_demo`, `call_to_action`. Locked in cursor. |
| `brand` | string | no | — | Brand / product name for the `brand` moment kind. Locked in cursor. |
| `whisper_model` | string | no | `base` | faster-whisper size for the AI path (base pre-warmed). One of: `tiny`, `base`, `small`. Locked in cursor. |
| `whisper_device` | string | no | `cpu` | Inference device for faster-whisper. One of: `cpu`, `auto`, `cuda`. Locked in cursor. |
| `use_proxy` | boolean | no | `true` | Route the request through Scrapier's residential proxy pool. Default: `true`. Leave as is unless support tells you otherwise. |
| `raw_data` | boolean | no | `false` | When true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under `raw_responses`, in place of the formatted items. When false (default) you get the formatted output. Pagination (`cursor` / `next_cursor`) works the same in both modes. |

## Response

HTTP 200. Results are in `data.transcript`. Sample from the live catalog, arrays trimmed to 3 items.

```json
{
  "success": true,
  "data": {
    "urls": "https://www.tiktok.com/@natgeo/video/7683891628230315295",
    "transcript": {
      "input_url": "https://www.tiktok.com/@natgeo/video/7683891628230315295",
      "video_id": "7683891628230315295",
      "url": "https://www.tiktok.com/@natgeo/video/7683891628230315295",
      "resolved_url": null,
      "status": "ok",
      "success": true,
      "reason": null,
      "status_code": 0,
      "error": null,
      "transcript": "Welcome to Africa. Welcome to Earth's wild home. See a new side to animals you know and meet some you've never seen before. This is the definitive look at the wildest continent on our planet. There's no place like Africa.",
      "transcript_source": "captions",
      "transcript_reason": "tiktok caption track",
      "transcript_vtt": "WEBVTT\n\n\n00:00:03.220 --> 00:00:04.320\nWelcome\n\n00:00:06.060 --> 00:00:07.600\nto Africa.\n\n00:00:08.300 --> 00:00:09.400\n...",
      "language": "eng-US",
      "language_code": "en",
      "language_requested": "en",
      "language_matched": true,
      "transcript_info": {
        "source": "captions",
        "language": "eng-US",
        "language_code": "en",
        "language_requested": "en",
        "language_matched": true,
        "is_auto_generated": true,
        "is_original_language": true,
        "variant": "big_caption",
        "provider": "tiktok",
        "model": null,
        "translated_from": null,
        "duration_seconds": 66.92,
        "segment_count": 11,
        "word_count": 40,
        "available_languages": [
          "eng-US"
        ],
        "reason": "tiktok caption track",
        "moments_requested": [
          "brand",
          "sponsor_read",
          "product_demo"
        ]
      },
      "segments": [
        {
          "start": 3.22,
          "end": 4.32,
          "text": "Welcome"
        },
        {
          "start": 6.06,
          "end": 7.6,
          "text": "to Africa."
        },
        {
          "start": 8.3,
          "end": 9.4,
          "text": "Welcome"
        }
      ],
      "caption_tracks": [
        {
          "language": "eng-US",
          "language_code": "en",
          "is_original": true,
          "is_auto_generated": true,
          "source": "ASR",
          "source_unabbreviated": "automatic speech recognition",
          "version": "1:big_caption",
          "variant": "big_caption",
          "format": "webvtt",
          "size_bytes": 571,
          "expires_at": "2026-09-22T10:01:09.000Z",
          "url": "https://v16-webapp.tiktok.com/9baa969fd53f6e963fbc38b0153039d9/6ab251e5/video/tos/alisg/to...",
          "url_list": [
            "https://v16-webapp.tiktok.com/9baa969fd53f6e963fbc38b0153039d9/6ab251e5/video/tos/alisg/to...",
            "https://v16-webapp.tiktok.com/9baa969fd53f6e963fbc38b0153039d9/6ab251e5/video/tos/alisg/to...",
            "https://www.tiktok.com/aweme/v1/play/?faid=1988&format=webvtt&is_play_url=1&language=eng-U..."
          ],
          "downloaded": true,
          "text": "Welcome to Africa. Welcome to Earth's wild home. See a new side to animals you know and meet some yo...",
          "segments": [
            {
              "start": 3.22,
              "end": 4.32,
              "text": "Welcome"
            },
            {
              "start": 6.06,
              "end": 7.6,
              "text": "to Africa."
            },
            "... 9 more segments"
          ],
          "segment_count": 11,
          "word_count": 40,
          "duration_seconds": 66.92,
          "error": null
        }
      ],
      "available_languages": [
        "eng-US"
      ],
      "moments": [],
      "brand": "Rolex",
      "id": "7683891628230315295",
      "text": "Presented by @ROLEX. Welcome to Africa 🌍 Africa Earth's Wild Home takes you deep into the heart of our wildest continent, bringing you closer to its animals, landscapes, and the people watching over it than ever before. Through its partnership with the National Geographic Society and as part of its Perpetual Planet Initiative, #Rolex supports expeditions exploring and protecting remarkable places around the world, a selection of which are featured in Africa Earth’s Wild Home. #PerpetualPlanet Africa Earth's Wild Home, narrated by Wunmi Mosaku, premieres Friday, October 2 at 8/7c on National Geographic. Streaming next day on @Disney+ and @hulu.",
      "text_language": "en",
      "create_time": 1789045447,
      "create_time_iso": "2026-09-10T13:04:07.000Z",
      "location_created": "GB",
      "is_ad": false,
      "has_tik_tok_shop_product": false,
      "author_meta": {
        "id": "6780344874811442181",
        "name": "natgeo",
        "profile_url": "https://www.tiktok.com/@natgeo",
        "nick_name": "National Geographic",
        "verified": true,
        "signature": "Step into wonder and find your inner explorer with National Geographic 🌎",
        "bio_link": null,
        "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/324924e171e481040a1ea202962f6e07...",
        "commerce_user_info": {
          "commerce_user": false
        },
        "private_account": false,
        "room_id": "",
        "tt_seller": false,
        "create_time": 1578672517,
        "has_active_story": false,
        "following": 62,
        "friends": 0,
        "fans": 9600000,
        "heart": 54600000,
        "video": 1506,
        "digg": 3142,
        "original_avatar_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/324924e171e481040a1ea202962f6e07...",
        "sec_uid": "MS4wLjABAAAAEf96k3JW8-3eOhgzgQswlFF6ZDnn1dzqWWorJjwDsiNZymqTtvOcFhp_RiYYST6s",
        "avatar_thumb": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/324924e171e481040a1ea202962f6e07...",
        "is_embed_banned": false,
        "is_ad_virtual": false
      },
      "music_meta": {
        "music_name": "original sound",
        "music_author": "National Geographic",
        "music_original": true,
        "play_url": "https://v16m.tiktokcdn.com/11e3cea617be6b8c284c0917057662f6/6ab10065/video/tos/alisg/tos-a...",
        "cover_medium_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/324924e171e481040a1ea202962f6e07...",
        "original_cover_medium_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/324924e171e481040a1ea202962f6e07...",
        "music_id": "7683891712992774942",
        "music_album": null,
        "duration": 72,
        "precise_duration": 72.673,
        "is_copyrighted": false,
        "is_commerce_music": false
      },
      "location_meta": null,
      "web_video_url": "https://www.tiktok.com/@natgeo/video/7683891628230315295",
      "video_meta": {
        "height": 1024,
        "width": 576,
        "duration": 72,
        "cover_url": "https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/oMAACXiIEiA1iUUfjqiKiECG7sV2q...",
        "definition": "540p",
        "format": "mp4",
        "ai_video_description": null,
        "ai_video_summary": null,
        "original_cover_url": "https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/ocLRlIqwP6EqABiqiPBIpimKAEBaB...",
        "dynamic_cover_url": "https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/oMAACXiIEiA1iUUfjqiKiECG7sV2q...",
        "video_id": "v15044gf0000dahag47og65gkpkkv5bg",
        "bitrate": 1465326,
        "codec_type": "h264",
        "video_quality": "normal",
        "size_bytes": 13301315,
        "has_original_audio": true,
        "auto_caption_enabled": true,
        "no_caption_reason": null,
        "no_caption_reason_text": null,
        "original_language": "eng-US",
        "play_addr": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-ve-37c799-sg/oIPvOIB5EwQMr2K...",
        "play_urls": [
          {
            "gear": "normal_540_0",
            "bitrate": 1465326,
            "codec": "h264",
            "quality": 20,
            "width": 576,
            "height": 1024,
            "size_bytes": 13301315,
            "url": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-ve-37c799-sg/oIPvOIB5EwQMr2K..."
          },
          "... 2 more renditions"
        ]
      },
      "digg_count": 17700,
      "share_count": 536,
      "play_count": 124200,
      "collect_count": 1027,
      "comment_count": 291,
      "repost_count": 0,
      "mentions": [
        "@rolex",
        "@disneyplus",
        "@hulu"
      ],
      "detailed_mentions": [
        {
          "id": "6901691802736608258",
          "name": "rolex",
          "sec_uid": "MS4wLjABAAAAC-8aDAW20w1Nnhh64s-kBh8ryXOkdAp9xW0yBVY002RFH7g7Dm2YNqUD1Q8Pz9IZ",
          "profile_url": "https://www.tiktok.com/@rolex"
        },
        {
          "id": "6844178288162063365",
          "name": "disneyplus",
          "sec_uid": "MS4wLjABAAAAqUNM3kSR5Ftp2-qS8tMXPcOX8sQIrztPZ6xbXF19zZMi805WqA158zLCL15WnGHL",
          "profile_url": "https://www.tiktok.com/@disneyplus"
        },
        {
          "id": "6647632235926503429",
          "name": "hulu",
          "sec_uid": "MS4wLjABAAAAM4MY_0Mngt5neJyXf3HiDcYRyCBv_dMx1DU4OpbQNbNThk2QRZLWPKgSidSUqAd8",
          "profile_url": "https://www.tiktok.com/@hulu"
        }
      ],
      "hashtags": [
        {
          "id": "18881",
          "name": "rolex",
          "title": null,
          "cover": null
        },
        {
          "id": "7029280493263585285",
          "name": "perpetualplanet",
          "title": null,
          "cover": null
        }
      ],
      "effect_stickers": [],
      "is_slideshow": false,
      "is_pinned": false,
      "is_sponsored": false,
      "short_drama_series_info": null,
      "media_urls": [],
      "is_story": false,
      "submitted_video_url": "https://www.tiktok.com/@natgeo/video/7683891628230315295",
      "text_on_screen": [],
      "diversification_labels": [
        "Animals",
        "Nature"
      ],
      "is_aigc": false,
      "branded_content": false,
      "duet_enabled": null,
      "stitch_enabled": null,
      "share_enabled": true,
      "comments_enabled": true,
      "source": {
        "platform": "tiktok",
        "layer": "web:webapp",
        "fingerprint": "firefox135",
        "url": "https://www.tiktok.com/@natgeo/video/7683891628230315295",
        "app_region": "BD"
      },
      "warnings": [],
      "fetch_stats": {
        "requests": 2,
        "retries": 0,
        "waf_solved": 0,
        "akamai_denied": 0,
        "bytes_downloaded": 0,
        "ai_seconds": 0
      },
      "duration_ms": 634,
      "scraped_at": "2026-09-20T10:00:01.065Z"
    },
    "next_cursor": null
  }
}
```

## Response fields

| Field | Type | Example | Description |
|---|---|---|---|
| `urls` | string | `https://www.tiktok.com/@natgeo/video/76838916…` |  |
| `transcript` | object | `{…}` | The results. |
| `next_cursor` | null | `null` | Pass back as `cursor` for the next page. `null` on the last page. |
| `transcript.input_url` | string | `https://www.tiktok.com/@natgeo/video/76838916…` |  |
| `transcript.video_id` | string | `7683891628230315295` |  |
| `transcript.url` | string | `https://www.tiktok.com/@natgeo/video/76838916…` |  |
| `transcript.resolved_url` | null | `null` |  |
| `transcript.status` | string | `ok` |  |
| `transcript.success` | boolean | `true` |  |
| `transcript.reason` | null | `null` |  |
| `transcript.status_code` | integer | `0` |  |
| `transcript.error` | null | `null` |  |
| `transcript.transcript` | string | `Welcome to Africa. Welcome to Earth's wild ho…` |  |
| `transcript.transcript_source` | string | `captions` |  |
| `transcript.transcript_reason` | string | `tiktok caption track` |  |
| `transcript.transcript_vtt` | string | `WEBVTT 00:00:03.220 --> 00:00:04.320 Welcom…` |  |
| `transcript.language` | string | `eng-US` |  |
| `transcript.language_code` | string | `en` |  |
| `transcript.language_requested` | string | `en` |  |
| `transcript.language_matched` | boolean | `true` |  |
| `transcript.transcript_info` | object | `{…}` |  |
| `transcript.segments` | array | `[4 items]` |  |
| `transcript.caption_tracks` | array | `[1 item]` |  |
| `transcript.available_languages` | array | `[1 item]` |  |
| `transcript.moments` | array | `[]` |  |
| `transcript.brand` | string | `Rolex` |  |
| `transcript.id` | string | `7683891628230315295` |  |
| `transcript.text` | string | `Presented by @ROLEX. Welcome to Africa 🌍 Afr…` |  |
| `transcript.text_language` | string | `en` |  |
| `transcript.create_time` | integer | `1789045447` |  |
| `transcript.create_time_iso` | string | `2026-09-10T13:04:07.000Z` |  |
| `transcript.location_created` | string | `GB` |  |
| `transcript.is_ad` | boolean | `false` |  |
| `transcript.has_tik_tok_shop_product` | boolean | `false` |  |
| `transcript.author_meta` | object | `{…}` |  |
| `transcript.music_meta` | object | `{…}` |  |
| `transcript.location_meta` | null | `null` |  |
| `transcript.web_video_url` | string | `https://www.tiktok.com/@natgeo/video/76838916…` |  |
| `transcript.video_meta` | object | `{…}` |  |
| `transcript.digg_count` | integer | `17700` |  |
| `transcript.share_count` | integer | `536` |  |
| `transcript.play_count` | integer | `124200` |  |
| `transcript.collect_count` | integer | `1027` |  |
| `transcript.comment_count` | integer | `291` |  |
| `transcript.repost_count` | integer | `0` |  |
| `transcript.mentions` | array | `[3 items]` |  |
| `transcript.detailed_mentions` | array | `[3 items]` |  |
| `transcript.hashtags` | array | `[2 items]` |  |
| `transcript.effect_stickers` | array | `[]` |  |
| `transcript.is_slideshow` | boolean | `false` |  |
| `transcript.is_pinned` | boolean | `false` |  |
| `transcript.is_sponsored` | boolean | `false` |  |
| `transcript.short_drama_series_info` | null | `null` |  |
| `transcript.media_urls` | array | `[]` |  |
| `transcript.is_story` | boolean | `false` |  |
| `transcript.submitted_video_url` | string | `https://www.tiktok.com/@natgeo/video/76838916…` |  |
| `transcript.text_on_screen` | array | `[]` |  |
| `transcript.diversification_labels` | array | `[2 items]` |  |
| `transcript.is_aigc` | boolean | `false` |  |
| `transcript.branded_content` | boolean | `false` |  |
| `transcript.duet_enabled` | null | `null` |  |
| `transcript.stitch_enabled` | null | `null` |  |
| `transcript.share_enabled` | boolean | `true` |  |
| `transcript.comments_enabled` | boolean | `true` |  |
| `transcript.source` | object | `{…}` |  |
| `transcript.warnings` | array | `[]` |  |
| `transcript.fetch_stats` | object | `{…}` |  |
| `transcript.duration_ms` | integer | `634` |  |
| `transcript.scraped_at` | string | `2026-09-20T10:00:01.065Z` |  |

## Pagination

Single lookup: everything comes back in one call and `next_cursor` is always `null`.

## Errors

Failed calls are free. Branch on HTTP status; the message is in `error` (or `detail`). See https://docs.scrapier.io/errors.md

- **400** Bad input. The exact message varies by endpoint. `{"success":false,"error":"…"}`
- **402** Balance below the endpoint's price. `{"error":"Insufficient credits. Buy more to scrape more.","balance":1,"required":2}`
- **403** Invalid or unknown API key. `{"detail":"Authentication service unavailable or invalid API key."}`
- **429** Throttled — wait for Retry-After. `{"detail":"Request was throttled. Expected available in N seconds."}`
- **404** unknown slug · **503** busy (retry after `Retry-After`) · **5xx** upstream failure or timeout (retry with backoff).

## Notes

- The response data carries its own `success` field from the scraper. The outer `success` is what counts: an HTTP 200 with outer `success: true` is billed, even if the inner field says otherwise.
- This endpoint can take several minutes. Set your client timeout to at least 210 seconds.

## Related

- [TikTok Ad Library Leads](https://docs.scrapier.io/api-reference/tiktok/tiktok-ad-library-leads.md): Structured TikTok data: every input is optional. Single lookup, 3 credits per successful call.
- [TikTok Ad Library](https://docs.scrapier.io/api-reference/tiktok/tiktok-ads.md): Structured TikTok data: send `urls`. Cursor-paginated, 1 credit per successful call.
- [TikTok Ads Top](https://docs.scrapier.io/api-reference/tiktok/tiktok-ads-top.md): Structured TikTok data: every input is optional. Cursor-paginated, 1 credit per successful call.
- [TikTok Collection Videos](https://docs.scrapier.io/api-reference/tiktok/tiktok-collection-videos.md): Structured TikTok data: send `urls`. Cursor-paginated, 1 credit per successful call.
