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
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_onlyis not supported for Instagram and answers422 CAPABILITY_UNAVAILABLE. Send Instagram links withmode: "auto"ormode: "transcribe". Both run AI transcription at 2 credits per started minute and need a paid plan.
- Reels and video posts. Public
instagram.com/reel/...andinstagram.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_creditscaps 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.
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
- Submit a Reel with
POST /v1/jobs, or many withPOST /v1/batches. Always setmax_credits. - Wait with
GET /v1/jobs/{id}?wait=25, or receive a webhook. AI transcription takes roughly a quarter of the media length. - Read or export with
GET /v1/transcripts/{result_id}or/export?format=txt|json|srt|vtt.
| Mode | 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.
| 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.
| 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.
| 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) |
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.
- Create an account and choose a paid plan on the pricing page. The free plan covers YouTube and TikTok captions only.
- Create an API key in the dashboard and keep it on your server:
export TRANSCRIPTDOCK_API_KEY="td_live_..."# 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"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);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"))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.
wordscarries per word timing and aconfidencefrom 0 to 1.segmentsare caption sized and drive SRT and VTT exports.recognition.quality_statusisvalidated_language(accuracy checked by Transcript Dock),provider_supported(the model lists the language) orexperimental_language(quality may vary). It describes the language, not a guarantee for one transcript.- The job's
billing.kindisai_transcriptionandbilling.credits_chargedis the real cost.
Polling with ?wait=25 is fine for scripts. For pipelines, register a webhook and let Transcript Dock call you.
- Register an
httpsURL on the Webhooks page of the dashboard. Registering and disabling endpoints needs a signed in session. An API key can list endpoints but gets403 FORBIDDENwhen it tries to create one. The signing secret is shown once: store it like a password. - Pass the endpoint id as
webhook_endpoint_idwhen you create a job or a batch. - Transcript Dock sends
job.succeeded,job.failedorbatch.completedwhen 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.
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.
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.
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 helpPlain 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.
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/mcpThen 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.
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.
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.
| 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 |
Want transcripts without writing code? The Transcript Dock extension for Chrome shows transcripts beside YouTube, TikTok and Instagram videos. More at transcriptdock.com/extension.
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.
- Website: transcriptdock.com
- Docs: quickstart, API reference, sources
- OpenAPI spec: openapi.yaml
- Pricing: transcriptdock.com/pricing
- Changelog: docs/changelog
- Contact: transcriptdock@volods.com
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.
