Instagram and TikTok Indexing API
Captain indexes public Instagram and TikTok posts by URL. Each post becomes searchable documents: its soundtrack or full video, its caption, and on Instagram the pictures of an image post or carousel. Send up to 20 links in one request.
Instagram's and TikTok's terms both restrict automated access to their services. Each customer is responsible for how it uses these endpoints.
What gets indexed
| Part of the post | Indexed as | Billing |
|---|---|---|
Video, mode: "audio" (default) | The soundtrack, transcribed | 5 credits per audio minute |
Video, mode: "video" | Frame descriptions plus the transcribed soundtrack | 20 credits per video minute |
Caption (include_caption, default true) | A small text document | Text rate |
Instagram pictures (include_images, default true) | One image document per picture | Image rate |
Audio is the default mode. It costs a quarter of video. Use video
when what appears on screen matters for search.
- Instagram carousels index every picture and every video in the post. Each video is its own document.
- TikTok audio mode still downloads the whole video, because TikTok offers no audio-only download. Only the audio minutes are billed.
- TikTok photo slideshows index their caption and audio only. The photos
are not indexed, and the post's
reasonisphotos_not_available. - Comments are never indexed.
Indexing
curl -X POST "https://api.filesearch.dev/v2/collections/{collection_name}/index/instagram" \
-H "Authorization: Bearer $CAPTAIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.instagram.com/reel/CxYz123AbC/",
"https://www.instagram.com/p/DaBc456XyZ/"
]
}'Supported links: instagram.com/p/{shortcode}/, /reel/{shortcode}/,
/reels/{shortcode}/ and /tv/{shortcode}/, with or without a
/{username}/ prefix. Shortcodes are case-sensitive, so CxYz123AbC and
cxyz123abc are different posts.
Share links (instagram.com/share/...) are refused with a 400. Open the
link in a browser and copy the post's address instead.
TikTok
curl -X POST "https://api.filesearch.dev/v2/collections/{collection_name}/index/tiktok" \
-H "Authorization: Bearer $CAPTAIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.tiktok.com/@demo/video/7301234567890123456",
"mode": "video"
}'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}/. Captain follows a short
link to its post, so a short link and the full link to the same video index
it once.
Options
| Field | Default | Meaning |
|---|---|---|
url or urls | One link, or up to 20 (5 for organizations on a trial). A post named twice is indexed once. | |
mode | audio | audio or video. |
include_caption | true | Index the caption as its own document. |
include_images | true | Instagram only. Index the pictures of an image post or carousel. |
skip_existing | true | Skip posts already in the collection. |
overwrite_existing | false | Delete and re-index posts already in the collection. Requires skip_existing: false. |
processing_type | basic | Parsing tier for captions and pictures. Video and audio always go through the media pipeline. |
custom_metadata | Metadata attached to every document the job writes. | |
mask_pii | false | Mask personal data in captions and transcripts. See PII Masking. |
pii_engine, pii_fallback, pii_fields, pii_instructions | The masking options every index request takes. Each requires mask_pii. See PII Masking. |
Any field not in this table returns 422.
Running it again
A second call with the same links skips every post already in the collection, at no cost. That includes a post whose caption was edited since the first call: the caption is not re-read.
To pick up an edited caption, send overwrite_existing: true and
skip_existing: false. Each post is deleted and indexed again, and billed
again.
Documents
Each document's uri is the post's address with a fragment naming the part:
| Part | uri |
|---|---|
| Video or audio | https://www.instagram.com/p/CxYz123AbC/#mode=audio (#mode=video&item=2 for a carousel video) |
| Caption | https://www.instagram.com/p/CxYz123AbC/#caption |
| Picture | https://www.instagram.com/p/CxYz123AbC/#image=1 |
| TikTok | https://www.tiktok.com/@_/video/7301234567890123456#mode=audio, or #caption |
TikTok addresses use @_ in place of the author, so a renamed account keeps
the same documents. The real author link is in tiktok_url.
Metadata
Each document carries metadata about its post, usable in search filters:
| Platform | Keys |
|---|---|
instagram_shortcode, instagram_url, instagram_author, instagram_posted_at, instagram_media_index (carousels) | |
| TikTok | tiktok_video_id, tiktok_url, tiktok_author, tiktok_posted_at |
| Both, video and audio documents | social_duration_seconds |
These keys are reserved. Sending one in custom_metadata on any index
request returns 400.
Job results
GET /v2/jobs/{job_id} returns a source_report object for these jobs:
{
"source_report": {
"source": "instagram",
"posts_seen": 3,
"posts_indexed": 1,
"posts_skipped_unchanged": 1,
"posts_failed": 1,
"social_posts": [
{
"platform": "instagram",
"post_id": "CxYz123AbC",
"url": "https://www.instagram.com/p/CxYz123AbC/",
"status": "indexed",
"mode_used": "audio",
"items": [
{ "kind": "audio", "status": "queued", "file_name": "instagram_CxYz123AbC.m4a" },
{ "kind": "caption", "status": "queued", "file_name": "instagram_CxYz123AbC_caption.txt" }
],
"reason": null
},
{ "platform": "instagram", "post_id": "DaBc456XyZ", "status": "skipped_unchanged", "items": [], "reason": null },
{ "platform": "instagram", "post_id": "EfGh789Ijk", "status": "failed", "items": [], "reason": "private_or_login_required" }
]
}
}Each item in items has its own status: queued (handed to indexing),
skipped (already in the collection) or failed, with a reason from the
table below. A post can be indexed while some of its items failed. For
example, a carousel of silent videos in audio mode indexes its caption, and
each video item fails with no_audio_stream. Carousel items also carry their
position in the post as index, from 1.
When every post in a job fails, the job fails and error_message says why
in one sentence, for example:
Instagram import failed: none of the 3 posts could be indexed. They may have been deleted or made private, or the platform refused our request. Check the links before you try again.When some fail, the job completes and the failed posts are listed with their reason.
reason | Meaning |
|---|---|
blocked_by_platform | The 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_required | The post is private, age-restricted or needs a login. |
not_found | The post was deleted, or the link does not point to a post. |
too_long | The video is longer than 10 minutes, so it was not indexed. |
unsupported_post_type | A post Captain cannot index, such as a live stream. |
ip_blocked_region | The 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_out | Fetching the post did not finish in time. Send fewer links per request. |
no_audio_stream | The video has no sound to transcribe, as with some music reels and silent carousel videos. Use mode: "video". |
photos_not_available | TikTok 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.
A known issue: when a post's video cannot be downloaded after the job has
queued it, the job can show that video as still embedding for up to 30
minutes, then fail it as embedding_stalled instead of giving the real
reason. A fix is tracked.
Limits
- 20 links per request, 5 for organizations on a trial.
- Videos longer than 10 minutes are not indexed.
- Only public posts. Private posts and posts that need a login fail with
private_or_login_required. - Not imported: profiles, hashtags, stories, comments, and TikTok slideshow photos.
- Posts are fetched when the job runs. A post edited or deleted later is not updated in the collection until it is indexed again.