> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok Live Data

> Fetch current TikTok profiles, videos, comments, media URLs, and transcripts.

The TikTok live endpoints return normalized profile and video data. The API can reuse recent source data, so use `scraped_at` to assess when each result was collected.

## Endpoints

| Endpoint                                       | Returns                                |                                         Credits |
| ---------------------------------------------- | -------------------------------------- | ----------------------------------------------: |
| `GET /v1/raw/tiktok/profile/{username}`        | Profile identity and current metrics   |                                           `0.2` |
| `GET /v1/raw/tiktok/profile/{username}/videos` | One cursor-paginated video page        |                                           `0.2` |
| `GET /v1/raw/tiktok/video`                     | Video details, metrics, and media URLs |                                           `0.2` |
| `GET /v1/raw/tiktok/video/comments`            | One cursor-paginated comment page      |                                           `0.2` |
| `GET /v1/raw/tiktok/video/comment/replies`     | One cursor-paginated reply page        |                                           `0.2` |
| `GET /v1/raw/tiktok/music`                     | Sound clip metadata by `music_id`      |                                           `0.2` |
| `GET /v1/raw/tiktok/search/users`              | One page of user search results        |                                           `0.2` |
| `GET /v1/raw/tiktok/search/videos`             | One page of video search results       |                                           `0.2` |
| `GET /v1/raw/tiktok/hashtag/videos`            | One page of videos under a hashtag     |                                           `0.2` |
| `GET /v1/raw/tiktok/music/videos`              | One page of videos using a sound clip  |                                           `0.2` |
| `GET /v1/raw/tiktok/video/captions`            | Available captions without generation  |                                           `0.2` |
| `GET /v1/raw/tiktok/video/transcript`          | Plain text and timestamped segments    |                                           `2.5` |
| `POST /v1/raw/tiktok/videos`                   | Up to 20 video results                 |                       `0.2` per successful item |
| `POST /v1/raw/tiktok/video/transcripts`        | Up to 10 transcript results            | `2.5` auto / `0.2` captions per successful item |

Sound metadata uses the TikTok sound clip ID, not an album or recording ID. Unknown fields are `null`; audio and cover URLs are temporary upstream links, not durable downloads.

Use a video's `music.music_id` to request sound metadata or videos using that sound. Keep the ID as a string: converting it to a JavaScript number can lose precision. A `null` ID means the sound cannot be identified from that response.

To list videos using a sound, pass its clip ID as `music_id` to
`GET /v1/raw/tiktok/music/videos`. The response contains `data.music_id`,
`data.videos`, `data.has_more`, `data.next_cursor`, and `data.scraped_at`.
Continue with the returned cursor and the same music ID. Duplicate videos are
preserved; each successful page, including an empty page, costs 0.2 account credits.
Video media links are temporary.

Stop pagination on `404 not_found`, including when a previous page returned
`has_more: true`. A continuation cursor does not guarantee another available page.
A `404` is an error, not proof that you retrieved every video. Account billing does
not charge for that failed page; settled x402 and MPP payments are not refunded.

```bash theme={null}
curl --get 'https://api.influship.com/v1/raw/tiktok/music/videos' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode "music_id=$TIKTOK_MUSIC_ID"
```

An empty terminal page has this shape:

```json theme={null}
{
  "data": {
    "music_id": "789",
    "videos": [],
    "has_more": false,
    "next_cursor": null,
    "scraped_at": "2026-09-06T12:00:00Z"
  }
}
```

User search accepts a `query` of 1–100 characters and an optional opaque `cursor`.
Pass `next_cursor` with the same query to continue. Results include profile identity,
biography, verification, and audience counts; unknown fields are `null`, not zero.
Each successful page costs 0.2 credits, including an empty page.

Video search uses the same `query` and `cursor` parameters at
`GET /v1/raw/tiktok/search/videos`. Results are relevance-ordered and returned in
`data.videos`, using the same video fields as video lookup. Duplicate results are
preserved. Keep the query unchanged across pages and use `has_more` and
`next_cursor`, not the number of videos, to determine whether to continue.

Hashtag videos use `GET /v1/raw/tiktok/hashtag/videos` with a `hashtag` name
without `#` or spaces. The response contains `data.hashtag`, `data.videos`,
`has_more`, and `next_cursor`. Keep the hashtag unchanged when continuing.
Each successful page costs 0.2 account credits, including empty pages.

```bash theme={null}
curl --get 'https://api.influship.com/v1/raw/tiktok/hashtag/videos' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode 'hashtag=cooking'
```

```bash theme={null}
curl --get 'https://api.influship.com/v1/raw/tiktok/search/users' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode 'query=cooking'
```

```json theme={null}
{
  "data": {
    "query": "cooking",
    "users": [],
    "has_more": false,
    "next_cursor": null,
    "scraped_at": "2026-09-06T12:00:00Z"
  }
}
```

For captions only, call `GET /v1/raw/tiktok/video/captions?url=...`. This never generates a transcript. Unavailable captions return `404 transcript_not_available`; successful cached captions cost the ordinary 0.2-credit rate. Use the transcript endpoint when you want automatic transcription if captions are unavailable.

One credit is \$0.01. See [Pricing](/concepts/pricing) for billing and payment-rail rules.
The listed credit price applies to each successful response, including one that reuses recent source data.

TikTok content is always resolved against the US region. The optional `region`
parameter is retained for compatibility and only accepts `US`.

## Fetch a profile

Pass a bare username or include the leading `@`.

```bash theme={null}
curl 'https://api.influship.com/v1/raw/tiktok/profile/creator' \
  -H "X-API-Key: $INFLUSHIP_API_KEY"
```

The response includes the stable TikTok user ID, username, display name, biography, profile URL, audience counts, verification, privacy, and business status.

## List profile videos

```bash theme={null}
curl 'https://api.influship.com/v1/raw/tiktok/profile/creator/videos?sort_by=latest&region=US' \
  -H "X-API-Key: $INFLUSHIP_API_KEY"
```

Pass `next_cursor` back as `cursor` while `has_more` is `true`. Each request returns the complete source page. Cursors are opaque, so store and return the value unchanged.

Keep the same resource and query options for every page. Cursors may contain up to 2,048 characters and are temporary; do not reuse them for another profile, video, or sort order. If a cursor is invalid or expired, restart pagination without it.

Each video has a stable `video_id`, canonical TikTok URL, author, description, timestamps, engagement counts, hashtags, music metadata, and media fields. Slideshows use `media_type: "slideshow"` and place image URLs in `images`.

## Fetch one video and its file URL

Pass the TikTok URL as a query parameter.

```bash theme={null}
VIDEO_URL='https://www.tiktok.com/@creator/video/7517114944362499342'

curl --get 'https://api.influship.com/v1/raw/tiktok/video' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode "url=$VIDEO_URL" \
  --data-urlencode 'region=US'
```

For a regular video, `data.video.video_url` contains a directly downloadable media URL when the source exposes one. The URL is signed and temporary. Download the file promptly instead of storing the URL for later use. `video_url` is `null` when no downloadable video stream is available, including slideshow-only posts.

```bash theme={null}
curl --get -s 'https://api.influship.com/v1/raw/tiktok/video' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode "url=$VIDEO_URL" \
  | jq -r '.data.video.video_url // empty' \
  | xargs -r wget -O tiktok-video.mp4
```

## Fetch comments

```bash theme={null}
curl --get 'https://api.influship.com/v1/raw/tiktok/video/comments' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode "url=$VIDEO_URL"
```

Comments include text, creation time, likes, replies, pinned status, and normalized author data. Use `next_cursor` for the next source page.
`video_id` can be `null` when a short share URL returns an empty comment page and the source does
not provide the resolved video ID.

## Fetch comment replies

```bash theme={null}
curl --get 'https://api.influship.com/v1/raw/tiktok/video/comment/replies' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode "url=$VIDEO_URL" \
  --data-urlencode "comment_id=$COMMENT_ID"
```

Use a numeric `comment_id` from the comments response. IDs starting with `synthetic_` cannot be used to fetch replies. The response contains `video_id`, `parent_comment_id`, `comments`, `total`, `has_more`, `next_cursor`, and `scraped_at`. Keep the video URL and parent ID unchanged when passing `next_cursor` to fetch another page. Each successful page costs 0.2 credits, including an empty final page. An invalid or expired cursor returns `400`; restart without a cursor.

## Fetch a transcript

```bash theme={null}
curl --get 'https://api.influship.com/v1/raw/tiktok/video/transcript' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  --data-urlencode "url=$VIDEO_URL"
```

```json theme={null}
{
  "data": {
    "video_id": "7517114944362499342",
    "url": "https://www.tiktok.com/@creator/video/7517114944362499342",
    "transcript": "Welcome back. Today we are testing the new recipe.",
    "full_text": "Welcome back. Today we are testing the new recipe.",
    "segments": [
      { "start_ms": 0, "end_ms": 1480, "text": "Welcome back." },
      {
        "start_ms": 1480,
        "end_ms": 4210,
        "text": "Today we are testing the new recipe."
      }
    ],
    "word_count": 9,
    "language": "en",
    "source": "generated",
    "duration_seconds": 4.21,
    "scraped_at": "2026-08-12T10:00:00.000Z"
  }
}
```

`source` is `captions` or `generated`, and `language` reports the detected language. The detected-language transcript is reused on later requests. Every delivered transcript costs 2.5 credits, including a reused response. This is a flat price within the supported processing limits, not a per-minute charge.

Transcript generation can run for up to 180 seconds. Set a timeout of at least 190 seconds when you call this endpoint with a custom HTTP client. The generated Influship SDK uses a 210-second default timeout.

Automatic generation supports videos up to 10 minutes long. Longer videos without usable captions return `422 transcription_limit_exceeded`; increasing your client timeout does not remove this limit.

## Batch videos and transcripts

Send 1–20 URLs to `POST /v1/raw/tiktok/videos`, or 1–10 URLs to
`POST /v1/raw/tiktok/video/transcripts`. Transcript batches accept `mode: "auto"`
(the default) or `mode: "captions"`. Captions mode never generates a transcript.

```bash theme={null}
curl 'https://api.influship.com/v1/raw/tiktok/video/transcripts' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"urls":["https://www.tiktok.com/@creator/video/7517114944362499342"],"mode":"captions"}'
```

The response has `data.requested`, `data.succeeded`, `data.failed`, and ordered
`data.items`. Each item contains its input `url`, a `success` boolean, and either
`data` or an error `status` and `error`. Transcript batches also return `data.mode`.
An HTTP `200` batch can contain failed items, including an entirely failed batch;
check each item rather than only the HTTP status.

Duplicate URLs remain separate entries. API-key and OAuth billing counts successful
entries only. x402 and MPP quote all requested entries and do not refund settled
payments for failed items. The premium is applied to the total batch price, rounded
up once to whole cents with a one-cent minimum. Ten auto transcripts quote \$0.30;
ten caption-only transcripts quote \$0.03. Retry only the entries you need, and
remember that each new premium payment is a separate charge.

## URL and retry rules

Video-level endpoints accept HTTPS URLs on `tiktok.com` and its subdomains, including `vm.tiktok.com` and `vt.tiktok.com`. Other hosts return `400 validation_error` before the source request runs.

| Status | Code                           | Meaning                                                        |
| -----: | ------------------------------ | -------------------------------------------------------------- |
|  `400` | `validation_error`             | Invalid input or an invalid or expired pagination cursor       |
|  `403` | `forbidden`                    | The requested resource is private                              |
|  `404` | `not_found`                    | The requested resource was not found                           |
|  `404` | `transcript_not_available`     | The video has no usable caption or media source                |
|  `422` | `transcription_limit_exceeded` | The uncaptioned media exceeds the synchronous transcript limit |
|  `503` | `transcription_unavailable`    | Transcript generation is temporarily unavailable               |
|  `503` | `service_unavailable`          | Live TikTok data is temporarily unavailable                    |
|  `502` | `upstream_contract_broken`     | Source data cannot be processed; the failure has been reported |

Retry `503` responses with bounded exponential backoff and jitter. Do not automatically retry `400`, `403`, `404`, `422`, or `502 upstream_contract_broken`. Retrying a settled x402 or MPP request requires another payment; use account billing when you need successful-operations-only charging.

## Payment rails

The endpoints accept API keys, OAuth, x402, and MPP when those payment methods are enabled. API-key and OAuth requests are charged for successful operations. x402 and MPP use the advertised request price once payment settles, including when the final endpoint response is an error. A successful x402 settlement returns a `PAYMENT-RESPONSE` header, while MPP returns a `Payment-Receipt`. See [x402](/guides/x402) and [MPP](/guides/mpp) before choosing a no-key rail.