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 postIndexed 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
Instagram pictures (include_images, default true)One image document per pictureImage 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 reason is photos_not_available.
  • Comments are never indexed.

Indexing

Instagram

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

FieldDefaultMeaning
url or urlsOne link, or up to 20 (5 for organizations on a trial). A post named twice is indexed once.
modeaudioaudio or video.
include_captiontrueIndex the caption as its own document.
include_imagestrueInstagram only. Index the pictures of an image post or carousel.
skip_existingtrueSkip posts already in the collection.
overwrite_existingfalseDelete and re-index posts already in the collection. Requires skip_existing: false.
processing_typebasicParsing tier for captions and pictures. Video and audio always go through the media pipeline.
custom_metadataMetadata attached to every document the job writes.
mask_piifalseMask personal data in captions and transcripts. See PII Masking.
pii_engine, pii_fallback, pii_fields, pii_instructionsThe 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:

Parturi
Video or audiohttps://www.instagram.com/p/CxYz123AbC/#mode=audio (#mode=video&item=2 for a carousel video)
Captionhttps://www.instagram.com/p/CxYz123AbC/#caption
Picturehttps://www.instagram.com/p/CxYz123AbC/#image=1
TikTokhttps://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:

PlatformKeys
Instagraminstagram_shortcode, instagram_url, instagram_author, instagram_posted_at, instagram_media_index (carousels)
TikToktiktok_video_id, tiktok_url, tiktok_author, tiktok_posted_at
Both, video and audio documentssocial_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.

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.
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.

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.
Was this page helpful?