Index TikTok

POSThttps://api.filesearch.dev/v2/collections/:collection_name/index/tiktok

Index public TikTok videos into a collection.

Audio is the default mode. Each post becomes up to two documents:

PartIndexed asBilling
Video, mode: "audio" (default)The soundtrack, transcribed5 credits per audio minute
Video, mode: "video"Frame descriptions plus the transcribed soundtrack20 credits per video minute
Caption (include_caption, default true)A small text documentText rate

TikTok offers no audio-only download, so audio mode still downloads the whole video. Only the audio minutes are billed. Photo slideshows index their caption and audio only. The photos are not indexed, and the post's reason is photos_not_available.

Supported links. tiktok.com/@{user}/video/{id} and tiktok.com/@{user}/photo/{id}, and the short links vm.tiktok.com/{code}/, vt.tiktok.com/{code}/ and tiktok.com/t/{code}/, which Captain follows to the post.

Metadata. Each document carries tiktok_video_id, tiktok_url, tiktok_author and tiktok_posted_at. Video and audio documents also carry social_duration_seconds. These keys are reserved and cannot be sent in custom_metadata.

Re-running a job. With skip_existing: true (the default) a post already in the collection is skipped at no cost. That includes a post whose caption was edited since. To pick up an edited caption, send overwrite_existing: true with skip_existing: false. Sending both as true returns a 400.

Limits. Up to 20 URLs per request, 5 for organizations on a trial. A post named twice is indexed once. Videos longer than 10 minutes are not indexed. Only public posts work. Profiles, hashtags, stories and comments are not imported.

Results. The response is a job_id. GET /v2/jobs/{job_id} returns source_report with posts_seen, posts_indexed, posts_skipped_unchanged and posts_failed, and social_posts: one entry per post with its status (indexed, skipped_unchanged or failed), mode_used, the documents it became (items) and a reason code. When every post fails, the job fails and error_message says why.

reasonMeaning
blocked_by_platformThe post may have been deleted or made private, or the platform refused the request. From outside these look the same. Check the link, then try again.
private_or_login_requiredThe post is private, age-restricted or needs a login. Only public posts can be indexed.
not_foundThe post was deleted, or the link does not point to a post.
too_longThe video is longer than 10 minutes, so it was not indexed.
unsupported_post_typeA post Captain cannot index, such as a live stream.
ip_blocked_regionThe post may have been deleted or made private, or the platform does not serve it to the regions Captain fetches from. Check the link.
timed_outFetching the post did not finish in time. Send fewer links per request.
no_audio_streamThe video has no sound to transcribe, as with some music reels and silent carousel videos. Use mode: "video".
photos_not_availableTikTok only: a photo slideshow. The caption and audio were indexed, the photos were not.

The list grows over time, so treat an unknown code as informational.

Instagram's and TikTok's terms both restrict automated access to their services. Each customer is responsible for how it uses this endpoint.

Path parameters

collection_namestringRequired

Headers

authorizationstring or nullOptional

Request

This endpoint expects an object.

custom_metadatamap from strings to strings or integers or doubles or booleans or lists of strings or nullOptional

Custom metadata to attach to all indexed chunks. Keys must be strings. Values: str, int, float, bool, or List[str].

include_captionbooleanOptionalDefaults to true

When true (default), the post’s caption is indexed as its own small text document.

mask_piibooleanOptionalDefaults to false

When true, mask detected PII (emails, names, SSNs, etc.) in parsed text before embedding and storing.

modeenumOptionalDefaults to audio

How to index each post’s video. ‘audio’ (default): the soundtrack is transcribed and indexed, billed at 5 credits per audio minute. ‘video’: frames and the soundtrack are both indexed, billed at 20 credits per video minute. Posts longer than 10 minutes are not indexed.

Allowed values:audiovideo
overwrite_existingbooleanOptionalDefaults to false

When true, posts already in the collection are deleted and indexed again. Use it to pick up an edited caption. Requires skip_existing=false. Setting both to true returns a 400 error.

pii_engineenum or nullOptional

Masking engine for this job. jev (default): TypeSafe’s hosted Jev classifier model; supports pii_fields and pii_instructions; there is no fallback engine, so a file Jev cannot mask fails to index. presidio: the legacy pattern engine, built-in categories only (rejects pii_fields and pii_instructions with 422), never a fallback. Requires mask_pii to be true. The earlier names captain-jev and captain-presidio keep working as before.

Allowed values:jevpresidiocaptain-jevcaptain-presidio
pii_fallbackboolean or object or nullOptional

Retry policy for jev, as {“retry_budget_seconds”: n}. There are no fallback engines. A non-empty engines list answers 422. On the multipart file upload endpoint, send it as a JSON string form field. With the earlier engine name captain-jev it is true (default, fall back to captain-presidio) or false (fail the file).

pii_fieldslist of objects or nullOptional

Additional PII categories to mask for this job, on top of the built-in set. Requires mask_pii to be true. Up to 20 fields. Each masked value is replaced with the field’s tag in angle brackets and appears in the masking report under the field’s name.

pii_instructionsstring or nullOptional<=1000 characters

Plain-language guidance that steers what counts as personal data for this job, for the built-in categories and any pii_fields. For example: ‘Names of hospital staff may stay; patient names, record numbers and bed assignments must be masked.’ Requires mask_pii to be true. Up to 1,000 characters.

processing_typeenumOptionalDefaults to basic

Parsing tier for the caption and any images. Defaults to ‘basic’. The video or audio always goes through the media pipeline and bills per minute.

Allowed values:advancedbasicauto
skip_existingbooleanOptionalDefaults to true

When true (default), a post already in the collection is skipped at no cost, even if its caption has changed since. Set overwrite_existing to true (and this to false) to re-index edited posts.

urlstring or nullOptional

A single post URL. Provide either ‘url’ or ‘urls’, not both.

urlslist of strings or nullOptional

Up to 20 post URLs (5 for organizations on a trial). Provide either ‘url’ or ‘urls’, not both.

Response

Successful Response

job_idstring
statusstringOptionalDefaults to pending
custom_metadatamap from strings to any or nullOptional

The custom_metadata Captain accepted for this job, echoed back as validated. Null when none was supplied.

Errors

POST/v2/collections/:collection_name/index/tiktok
import requests

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"

headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    f"{BASE_URL}/v2/collections/my_documents/index/tiktok",
    headers=headers,
    json={"url": "https://www.tiktok.com/@demo/video/7301234567890123456"},
    timeout=60.0,
)
print(response.json())
200
{
  "job_id": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9-1795000000",
  "status": "pending"
}
Was this page helpful?