Skip to content

About

Instagram transcript API: AI transcription for public Reels and video posts, with a spend cap on every job. Examples, docs and an agent skill.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Transcript Dock for Instagram: pixel art camera on a wooden dock at sunset

Instagram Transcript API

Transcripts of public Instagram Reels and video posts through one API, with word timing and a spend cap on every job.

Website • API docs • Pricing • Quick start • Examples • Agent skill

API v1 OpenAPI 3.1 Instagram: paid plans Platform: Instagram, beta MCP ready PyPI version of transcriptdock License: MIT


This repo is the Instagram guide to the Transcript Dock API. The same API also covers YouTube, TikTok and your own files.

Instagram support is in beta and uses AI transcription only. Instagram has no caption path in Transcript Dock, so captions_only is not supported for Instagram and answers 422 CAPABILITY_UNAVAILABLE. Send Instagram links with mode: "auto" or mode: "transcribe". Both run AI transcription at 2 credits per started minute and need a paid plan.

Why use it for Instagram

  • Reels and video posts. Public instagram.com/reel/... and instagram.com/p/... video links work.
  • Word timing. AI transcription returns per word timing and confidence, plus caption sized segments for SRT and VTT.
  • Spend you control. max_credits caps every job. The media is measured first, and a Reel that would cost more fails with nothing charged.
  • Batches. Up to 10, 25 or 50 Reels in one atomic request on Starter, Pro and Scale.
  • Same transcript object as every other source, so one parser handles Instagram, YouTube, TikTok and your uploads.
  • Exports included. TXT, JSON, SRT and VTT, as often as you like, for free.

What it does not do: no captions mode, no Instagram profile or hashtag discovery, no private accounts, and no free plan access.

How it works

sequenceDiagram
    participant App as Your server
    participant TD as Transcript Dock
    App->>TD: POST /v1/jobs (mode auto, max_credits 20)
    TD-->>App: 202 job, status queued
    App->>TD: GET /v1/jobs/{id}?wait=25
    TD-->>App: 200 job, status succeeded, result_id
    App->>TD: GET /v1/transcripts/{result_id}
    TD-->>App: 200 text, segments, words
Loading
  1. Submit a Reel with POST /v1/jobs, or many with POST /v1/batches. Always set max_credits.
  2. Wait with GET /v1/jobs/{id}?wait=25, or receive a webhook. AI transcription takes roughly a quarter of the media length.
  3. Read or export with GET /v1/transcripts/{result_id} or /export?format=txt|json|srt|vtt.

Modes for Instagram

Mode Instagram What it does Cost
captions_only Not supported Answers 422 CAPABILITY_UNAVAILABLE 0
auto Supported, paid plans With no caption path on Instagram, this goes straight to AI transcription 2 credits per started minute, 60 second minimum
transcribe Supported, paid plans AI transcription of the audio 2 credits per started minute, 60 second minimum

Use language to hint the spoken language (a BCP 47 code such as es). Leave it out to detect the language. GET /v1/capabilities with your key shows instagram.captions_only: false and whether auto and transcribe are open to your plan.

Endpoints

Method Path What it does Credits
POST /v1/jobs Transcribe one Reel or video post 2 per started minute, 60 second minimum
GET /v1/jobs/{id}?wait=25 Job status, long poll Free
POST /v1/jobs/{id}/cancel Cancel before AI transcription starts Free
POST /v1/batches Many Reels in one atomic request Per item
GET /v1/batches/{id} Batch status and child jobs Free
GET /v1/transcripts/{id} Transcript JSON with word timing Free
GET /v1/transcripts/{id}/export txt, json, srt or vtt Free
GET /v1/capabilities What your key can do Free
GET /v1/usage Plan and credit balance Free

Full schemas: API reference, OpenAPI 3.1 and the compact docs/README.md.

Credit costs

What Credits
Caption transcript (YouTube, TikTok) 1 per successful transcript
AI transcription (any source) 2 per started minute, 60 second minimum
Video discovery (YouTube search, channel, playlist, TikTok profile) 1 per page
Caption language discovery (YouTube) 1
Failed job 0
Polling, transcript reads and exports 0
Idempotent replay (same key, same body) 0
Same video and options already transcribed in your workspace 0 (billing.kind: "cached")

While a job runs, its maximum cost is held (billing.credits_reserved). When it finishes, only the real cost is charged (billing.credits_charged) and the rest is released.

Worked examples

Job Credits
A 15 second Reel, auto 2 (the 60 second minimum)
A 60 second Reel, auto 2
A 61 second Reel, auto 4 (2 started minutes)
A 90 second video post, transcribe 4
A 10 minute video post, transcribe 20
A batch of 10 Reels, each under a minute 20
A Reel sent with captions_only 0 (rejected with CAPABILITY_UNAVAILABLE)
A 3 minute Reel with max_credits: 4 0 (fails with BUDGET_EXCEEDED, nothing charged)

Plans

One credit balance covers captions, AI transcription and discovery.

Free Starter Pro Scale
Price $0, no card $19 a month or $190 a year $49 a month or $490 a year $149 a month or $1,490 a year
Credits 50 every 30 days 2,000 a month 6,000 a month 20,000 a month
Extra credits Not available $8 per 1,000 $7 per 1,000 $6 per 1,000
Sources YouTube and TikTok captions YouTube, TikTok, Instagram, uploads, direct links YouTube, TikTok, Instagram, uploads, direct links YouTube, TikTok, Instagram, uploads, direct links
AI transcription Not included 2 credits a minute 2 credits a minute 2 credits a minute
Batch size 1 link 10 links 25 links 50 links
Submits a minute 10 60 120 300
Jobs in progress 10 100 500 2,000
Retention 7 days 30 days 90 days 90 days

Yearly billing gives 2 months free. Yearly plans still get their credits every month, and unused monthly credits do not roll over. Purchased credits never expire. Reads (job polling, transcripts, exports) have a separate limit of 120 a minute on every plan. Prices and limits can change: transcriptdock.com/pricing is the source of truth.

Quick start

  1. Create an account and choose a paid plan on the pricing page. The free plan covers YouTube and TikTok captions only.
  2. Create an API key in the dashboard and keep it on your server:
export TRANSCRIPTDOCK_API_KEY="td_live_..."

cURL

# AI transcription of a public Reel. max_credits 20 accepts Reels up to 10 minutes.
curl -sS -X POST https://www.transcriptdock.com/v1/jobs \
  -H "Authorization: Bearer $TRANSCRIPTDOCK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"source":{"url":"https://www.instagram.com/reel/REEL_ID/"},"mode":"auto","max_credits":20}'

# Wait for the job, up to 25 seconds per call
curl -sS "https://www.transcriptdock.com/v1/jobs/JOB_ID?wait=25" \
  -H "Authorization: Bearer $TRANSCRIPTDOCK_API_KEY"

# Export as SRT
curl -sS "https://www.transcriptdock.com/v1/transcripts/RESULT_ID/export?format=srt" \
  -H "Authorization: Bearer $TRANSCRIPTDOCK_API_KEY"

JavaScript (Node 18+, no dependencies)

import { randomUUID } from "node:crypto";

const API = "https://www.transcriptdock.com";
const auth = { Authorization: `Bearer ${process.env.TRANSCRIPTDOCK_API_KEY}` };

async function call(method, path, body, idempotencyKey) {
  const res = await fetch(API + path, {
    method,
    redirect: "error",
    headers: {
      ...auth,
      ...(body && { "Content-Type": "application/json" }),
      ...(idempotencyKey && { "Idempotency-Key": idempotencyKey }),
    },
    body: body && JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

// Instagram is AI transcription only: 2 credits per started minute, paid plans.
let job = await call("POST", "/v1/jobs", {
  source: { url: "https://www.instagram.com/reel/REEL_ID/" },
  mode: "auto",
  max_credits: 20, // up to 10 minutes
}, randomUUID());

while (!["succeeded", "failed", "cancelled"].includes(job.status)) {
  job = await call("GET", `/v1/jobs/${job.id}?wait=25`);
}

if (job.status !== "succeeded") throw new Error(`${job.status}: ${job.error?.code}`);
const transcript = await call("GET", `/v1/transcripts/${job.result_id}`);
console.log(`${job.billing.credits_charged} credits`, transcript.text);

Python (pip install transcriptdock)

import os
from uuid import uuid4
from transcriptdock import TranscriptDock, JobTimeoutError

client = TranscriptDock(os.environ["TRANSCRIPTDOCK_API_KEY"])

# Generate once per intended operation. Save this key and the returned job ID.
submission_key = str(uuid4())
job = client.create_job(
    {"source": {"url": "https://www.instagram.com/reel/REEL_ID/"},
     "mode": "auto", "max_credits": 20},
    idempotency_key=submission_key,
)
try:
    job = client.wait_for_job(job["id"], timeout=600)
except JobTimeoutError as error:
    print("Still running", error.job)
else:
    if job["status"] == "succeeded":
        print(client.export_transcript(job["result_id"], "srt"))
    else:
        print(job["status"], job.get("error"))

What you get back

Example data. An Instagram transcript from GET /v1/transcripts/{result_id}, trimmed to two words:

{
  "id": "22222222-2222-4222-8222-222222222222",
  "source": {
    "platform": "instagram",
    "media_id": "EXAMPLE123",
    "canonical_url": "https://www.instagram.com/reel/EXAMPLE123/",
    "title": null
  },
  "source_origin": "speech_recognition",
  "language": "en",
  "text": "Morning routine, take two.",
  "segments": [
    { "start": 0.24, "end": 1.9, "text": "Morning routine, take two." }
  ],
  "words": [
    { "start": 0.24, "end": 0.71, "text": "Morning", "confidence": 0.98 },
    { "start": 0.71, "end": 1.18, "text": "routine,", "confidence": 0.95 }
  ],
  "timing_granularity": "word",
  "duration_seconds": 14.6,
  "recognition": {
    "profile": "standard",
    "model": "set by the server",
    "quality_status": "validated_language"
  },
  "extraction_version": "worker-0.1.0",
  "created_at": "2026-11-18T10:00:41.000Z"
}
  • Times are in seconds.
  • words carries per word timing and a confidence from 0 to 1. segments are caption sized and drive SRT and VTT exports.
  • recognition.quality_status is validated_language (accuracy checked by Transcript Dock), provider_supported (the model lists the language) or experimental_language (quality may vary). It describes the language, not a guarantee for one transcript.
  • The job's billing.kind is ai_transcription and billing.credits_charged is the real cost.

Webhooks

Polling with ?wait=25 is fine for scripts. For pipelines, register a webhook and let Transcript Dock call you.

  1. Register an https URL on the Webhooks page of the dashboard. Registering and disabling endpoints needs a signed in session. An API key can list endpoints but gets 403 FORBIDDEN when it tries to create one. The signing secret is shown once: store it like a password.
  2. Pass the endpoint id as webhook_endpoint_id when you create a job or a batch.
  3. Transcript Dock sends job.succeeded, job.failed or batch.completed when the work is final.
{
  "event_id": "44444444-4444-4444-8444-444444444444",
  "type": "job.succeeded",
  "created_at": "2026-11-18T10:00:14.000Z",
  "job_id": "11111111-1111-4111-8111-111111111111",
  "batch_id": null,
  "result_id": "22222222-2222-4222-8222-222222222222",
  "metadata": { "order": "8812" },
  "error": null
}

The event does not carry the transcript text. Fetch or export result_id when you receive it.

Verify every delivery. Each request has three headers: X-TranscriptDock-Event-Id, X-TranscriptDock-Timestamp and X-TranscriptDock-Signature. The signature is a hex HMAC SHA256 of {event_id}.{timestamp}.{raw_body} keyed with your endpoint secret.

  • Compute it over the raw request body, before any JSON parsing.
  • Compare in constant time.
  • Reject timestamps more than five minutes away from your clock.
  • Answer with any 2xx within a few seconds, and do the slow work afterwards. Redirects are not followed.
  • Failed deliveries are retried with backoff, and an event can arrive more than once. Deduplicate on event_id.
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyTranscriptDock(eventId, timestamp, rawBody, signature, secret) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(`${eventId}.${timestamp}.`)
    .update(rawBody) // the exact bytes you received
    .digest("hex");
  return expected.length === String(signature).length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(String(signature)));
}

The full contract, including retries and payload fields, is in the webhook docs.

Errors

Every error has the same envelope. Quote request_id (also sent as the X-Request-Id header) when you contact support.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough credits. Buy credits or upgrade your plan to continue.",
    "retryable": false,
    "details": { "detail": "This job needs more credits than you have left." },
    "doc_url": "https://www.transcriptdock.com/docs/api-reference#error-codes"
  },
  "request_id": "66666666-6666-4666-8666-666666666666"
}

A job that fails after it was accepted still returns HTTP 200 on GET /v1/jobs/{id}, with status: "failed" and the same error object in error. Failed jobs cost nothing.

Code HTTP Retry What to do
INVALID_REQUEST 422 No A field is missing or malformed. details.detail names it.
INVALID_URL / UNSUPPORTED_SOURCE 422 No Send a supported https link.
CAPABILITY_UNAVAILABLE 422 No That mode is not available for this source. Check GET /v1/capabilities.
UNAUTHENTICATED 401 No Missing or invalid API key.
FORBIDDEN 403 No The key lacks the scope for this endpoint.
INSUFFICIENT_BALANCE 402 No Buy credits or upgrade.
PLAN_REQUIRED 402 No AI transcription, Instagram, uploads and larger batches need a paid plan.
BUDGET_EXCEEDED 402 No The measured cost is above max_credits. Nothing was charged. Raise the cap or skip the media.
IDEMPOTENCY_CONFLICT 409 No The key was used with a different body. Use a new key.
JOB_NOT_RETRYABLE 409 No The failure was final. Fix the input and submit a new job.
RATE_LIMITED 429 Yes Wait Retry-After seconds, then resend with the same idempotency key.
NO_CAPTIONS 422 No The video has no captions and the mode was captions_only. Use auto or transcribe.
LANGUAGE_UNAVAILABLE 422 No None of caption_languages exists on the video. Drop the list to take the default track.
SOURCE_NOT_FOUND / SOURCE_PRIVATE / SOURCE_AUTH_REQUIRED / SOURCE_REGION_RESTRICTED 422 No Only public, reachable media works.
DURATION_LIMIT_EXCEEDED / FILE_TOO_LARGE 413 No Media over 2 hours or 250 MB.
TIMESTAMPS_UNAVAILABLE 422 No No timing for SRT or VTT. Export txt or json.
SOURCE_RATE_LIMITED / SOURCE_BLOCKED / SOURCE_TIMEOUT 503 Yes The platform is throttling. The job retries automatically.
INTERNAL_ERROR 500 Yes Retry with the same idempotency key. Report the request id if it persists.

The full error list has every code.

Idempotency and spend caps

Two habits make the API safe to call from scripts, queues and agents.

Send an Idempotency-Key on every create. It is required on POST /v1/jobs, /v1/batches, /v1/video-discoveries, /v1/language-discoveries and /v1/jobs/{id}/retry. Use 8 to 128 printable ASCII characters.

  • Same key and same body: you get the original object back. Nothing is created or charged twice.
  • Same key and a different body: 409 IDEMPOTENCY_CONFLICT.
  • Generate the key once per intended operation and save it with your record. If a response is lost, resend the same body with the same key. Never resubmit blindly with a fresh key.
  • A good key is your own id for the thing you are transcribing, for example yt-dQw4w9WgXcQ-captions.
  • A retry (POST /v1/jobs/{id}/retry) needs a new key, because it is a new job.

Set max_credits on AI transcription. The media is measured first. If the cost would be above your cap, the job fails with BUDGET_EXCEEDED and nothing is charged. Without a cap the default covers the 2 hour maximum (240 credits).

Longest media you accept max_credits
1 minute 2
5 minutes 10
10 minutes 20
30 minutes 60
2 hours 240

max_credits is ignored for captions_only, which always costs 1 credit. The examples in this repo still send it, so a later switch to auto keeps a cap.

Examples

Every example reads TRANSCRIPTDOCK_API_KEY, sends an idempotency key and caps max_credits. Instagram jobs always run paid AI transcription, so read the comment at the top of each file first.

Example What it shows
curl/examples.sh Plan check, a Reel with auto and max_credits, a batch, wait, export, cancel
javascript/check-plan.mjs Free check: is Instagram open to this key, and how many credits are left
javascript/reel.mjs One Reel with mode: "auto" and a cap, words and SRT export
javascript/batch-reels.mjs Several Reels in one batch, each with its own cap
python/check_plan.py The free plan check with the transcriptdock package
python/reel.py One Reel with mode: "auto" and max_credits
python/batch_reels.py A batch of Reels, then each transcript as text
node examples/javascript/check-plan.mjs
node examples/javascript/reel.mjs "https://www.instagram.com/reel/REEL_ID/" 20
python examples/python/reel.py "https://www.instagram.com/reel/REEL_ID/" 20
bash examples/curl/examples.sh help

SDKs

Plain HTTP works everywhere, and every example in this repo uses either fetch or the Python SDK. Typed clients:

Language Package Status
Python transcriptdock on PyPI (source) Published
Go github.com/TranscriptDock/transcriptdock-go Published
Ruby transcriptdock gem (source) Published
PHP transcriptdock/transcriptdock on Packagist (source) Published
.NET TranscriptDock on NuGet (source) Published
JavaScript and TypeScript transcriptdock on npm (source) Published
Dart and Flutter transcriptdock on pub.dev (source) Published
Java com.transcriptdock:transcriptdock (source) Coming soon
Rust transcriptdock on crates.io (source) Coming soon
Swift Swift Package Manager, from: "0.1.0" (source) Published

Generating your own client? Start from the OpenAPI 3.1 spec (repo). No code at all: the n8n node (n8n-nodes-transcriptdock) and the Apify Actor.

MCP and AI agents

Hosted MCP server

Transcript Dock runs a hosted MCP server at https://www.transcriptdock.com/mcp (Streamable HTTP). It signs you in with OAuth, or accepts an API key as a bearer header. Use the www URL exactly: the apex domain redirects, and clients drop the Authorization header on a cross origin redirect.

claude mcp add --transport http transcriptdock https://www.transcriptdock.com/mcp

Then run /mcp in Claude Code and choose Authenticate. In the Claude apps, add https://www.transcriptdock.com/mcp as a custom connector. Cursor, Windsurf and other clients are covered in the MCP docs. A local stdio server is on npm as @transcriptdock/mcp (source).

The MCP tools include get_video_transcript (submit, wait and return text in one call), transcribe, get_job, get_transcript, wait_for_job, search_youtube, list_channel_videos, list_playlist_videos and list_tiktok_user_videos.

Agent skill in this repo

skills/instagram-transcript-api/SKILL.md teaches an agent to use the HTTP API safely: check capabilities, submit with an idempotency key and a max_credits cap, wait, export, ask before paid AI transcription, and never invent timestamps.

# Claude Code: install for every project
mkdir -p ~/.claude/skills
cp -r skills/instagram-transcript-api ~/.claude/skills/

# or for one project
mkdir -p .claude/skills
cp -r skills/instagram-transcript-api .claude/skills/

The skill reads your key from TRANSCRIPTDOCK_API_KEY. Never paste a key into a chat.

FAQ

Why is captions_only not supported for Instagram?

Transcript Dock has not proven that it can read Instagram's own captions reliably, so that path stays off. captions_only answers 422 CAPABILITY_UNAVAILABLE for Instagram links. Use auto or transcribe, which run AI transcription.

Can I use it on the free plan?

No. Instagram uses AI transcription, which needs a paid plan. On the free plan Instagram jobs answer 402 PLAN_REQUIRED.

What does a Reel cost?

2 credits per started minute with a 60 second minimum. Most Reels under a minute cost 2 credits. Set max_credits and a longer video fails with BUDGET_EXCEEDED before anything is charged.

Which links work?

Public Reels (instagram.com/reel/...) and public video posts (instagram.com/p/...). Media from private accounts or behind a login fails with a SOURCE_* error code, and a failed job costs nothing.

Can I list a profile's Reels?

Not today. Video discovery covers YouTube and TikTok only. Collect the Reel links yourself and submit them as a batch.

What does beta mean here?

Instagram support is newer than YouTube and TikTok support, and Instagram can limit access. When it does, jobs report SOURCE_RATE_LIMITED or SOURCE_BLOCKED and retry automatically. If a job finally fails, you are not charged.

More Transcript Dock repos

Repo Focus
transcriptdock-api The hub: every source, every endpoint, uploads and webhooks
youtube-transcript-api YouTube captions, automatic captions, AI transcription, search, channel and playlist discovery
tiktok-transcript-api TikTok captions, AI fallback, profile video discovery, batches

Chrome extension

Want transcripts without writing code? The Transcript Dock extension for Chrome shows transcripts beside YouTube, TikTok and Instagram videos. More at transcriptdock.com/extension.


Issues and feedback

This repo holds examples, docs and an agent skill for the hosted Transcript Dock API.

  • Found a bug in an example, or the API behaving differently from the docs? Open an issue and include the X-Request-Id.
  • Have an idea for a feature or a new example? Open a feature request.
  • Security issue? Email transcriptdock@volods.com instead of opening an issue.

See CONTRIBUTING.md before sending a pull request.

Links

License

The examples, docs and skill in this repository are released under the MIT License.

The Transcript Dock API is a hosted service covered by its Terms of Service.

About

Instagram transcript API: AI transcription for public Reels and video posts, with a spend cap on every job. Examples, docs and an agent skill.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors