Index Instagram
Index public Instagram posts, reels and IGTV videos into a collection.
Audio is the default mode. Each post becomes up to three kinds of document:
| Part | Indexed as | Billing |
|---|---|---|
Video or reel, mode: "audio" (default) | The soundtrack, transcribed | 5 credits per audio minute |
Video or reel, mode: "video" | Frame descriptions plus the transcribed soundtrack | 20 credits per video minute |
Caption (include_caption, default true) | A small text document | Text rate |
Pictures of an image post or carousel (include_images, default true) | One image document per picture | Image rate |
A carousel with several videos indexes each video as its own document.
Supported links. instagram.com/p/{shortcode}/, /reel/{shortcode}/, /reels/{shortcode}/ and /tv/{shortcode}/, with or without a /{username}/ prefix. Shortcodes are case-sensitive. Share links (instagram.com/share/...) are refused with a 400: open the link and copy the post's address instead.
Metadata. Each document carries instagram_shortcode, instagram_url, instagram_author, instagram_posted_at and, for carousels, instagram_media_index. 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.
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. Only public posts can be indexed. |
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.
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
Headers
Request
This endpoint expects an object.
Custom metadata to attach to all indexed chunks. Keys must be strings. Values: str, int, float, bool, or List[str].
trueWhen true (default), the post’s caption is indexed as its own small text document.
trueWhen true (default), the pictures in an image post or a carousel are indexed as images.
falseWhen true, mask detected PII (emails, names, SSNs, etc.) in parsed text before embedding and storing.
audioHow 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.
audiovideofalseWhen 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.
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.
jevpresidiocaptain-jevcaptain-presidioRetry 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).
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.
<=1000 charactersPlain-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.
basicParsing tier for the caption and any images. Defaults to ‘basic’. The video or audio always goes through the media pipeline and bills per minute.
advancedbasicautotrueWhen 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.
A single post URL. Provide either ‘url’ or ‘urls’, not both.
Up to 20 post URLs (5 for organizations on a trial). Provide either ‘url’ or ‘urls’, not both.
Response
Successful Response
pendingThe custom_metadata Captain accepted for this job, echoed back as validated. Null when none was supplied.
Errors
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/instagram",
headers=headers,
json={"url": "https://www.instagram.com/reel/CxYz123AbC/"},
timeout=60.0,
)
print(response.json()){
"job_id": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8-1795000000",
"status": "pending"
}