Skip to main content
Get Social Video Transcripts in TypeScript with the Supadata API
2026/11/17

Get Social Video Transcripts in TypeScript with the Supadata API

A runnable TypeScript example that fetches TikTok, Instagram, X, Facebook and YouTube transcripts with the Supadata API, with async jobs and retries.

To get a transcript from a TikTok, Instagram, X, Facebook or YouTube link in code, send a GET request to Supadata's /v1/transcript endpoint with the video URL and your key in the x-api-key header. Short videos return the transcript right away. Long ones return HTTP 202 with a jobId that you poll until it's done. The complete TypeScript script below handles both cases, plus rate limits.

Disclosure: this article contains a referral link to Supadata. If you sign up through it, the author may receive Supadata credits. It doesn't change the price you pay.

We use this API at FastScribe. When you paste a social video link into FastScribe's video link to text tool, Supadata fetches the transcript behind the scenes. This tutorial shows the same flow as a small standalone script you can run in a minute.

What you need

  • Node.js 18 or newer. The script uses the built-in fetch.
  • A Supadata API key. Create a free account at supadata.ai and copy your key from the dashboard. The free plan includes 100 credits a month.
  • tsx to run TypeScript without a build step. npx downloads it for you.

How the endpoint works

You need one endpoint. These are the responses to handle:

ResponseWhat it meansWhat to do
200 with contentThe transcript is readyUse it
202 with jobIdSupadata started a background job (long videos)Poll GET /v1/transcript/{jobId} about once a second
206 with error: "transcript-unavailable"No transcript could be producedTreat it as an error, even though 206 is a success code
429 with error: "limit-exceeded"You hit your rate or quota limitWait and retry

The parameters this script uses:

  • url: the video URL. URLSearchParams encodes it for you.
  • mode=auto: use the platform's existing captions when there are any, and fall back to AI generation. Use native to never pay for generation, or generate to always generate.
  • text=false: return timestamped chunks (text, offset and duration in milliseconds, lang) instead of one long string.
  • lang (optional): a preferred ISO 639-1 language code such as en or es.

The complete script

Save this as transcript.ts:

// transcript.ts — fetch a social video transcript with the Supadata API.
// Usage: SUPADATA_API_KEY=... npx tsx transcript.ts "<video url>" [lang]
import { writeFile } from 'node:fs/promises';

const API_BASE = process.env.SUPADATA_API_BASE ?? 'https://api.supadata.ai/v1';
const API_KEY = process.env.SUPADATA_API_KEY;

type Chunk = { text: string; offset: number; duration: number; lang: string };
type Transcript = { content: Chunk[]; lang: string; availableLangs: string[] };
type JobStatus = Partial<Transcript> & {
  status: 'queued' | 'active' | 'completed' | 'failed';
  error?: unknown;
};

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

// Retry-After can be seconds or an HTTP date; fall back to exponential backoff.
function retryDelayMs(res: Response, attempt: number): number {
  const header = res.headers.get('retry-after');
  if (header) {
    const seconds = Number(header);
    if (Number.isFinite(seconds)) return seconds * 1000;
    const date = Date.parse(header);
    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
  }
  return Math.min(1000 * 2 ** attempt, 30_000);
}

// GET with the API key; waits and retries on 429 (rate or quota limit).
async function apiGet(path: string, maxRetries = 5): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${API_BASE}${path}`, {
      headers: { 'x-api-key': API_KEY ?? '' },
    });
    if (res.status !== 429 || attempt >= maxRetries) return res;
    const wait = retryDelayMs(res, attempt);
    console.warn(`429 limit-exceeded, retrying in ${wait} ms`);
    await sleep(wait);
  }
}

async function fail(res: Response): Promise<never> {
  const body = (await res.json().catch(() => ({}))) as {
    error?: string;
    message?: string;
  };
  throw new Error(
    `${res.status} ${body.error ?? 'error'}: ${body.message ?? res.statusText}`
  );
}

// Long videos return 202 + jobId; poll until the job finishes.
async function waitForJob(jobId: string, timeoutMs = 15 * 60_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await apiGet(`/transcript/${jobId}`);
    if (!res.ok) await fail(res);
    const job = (await res.json()) as JobStatus;
    if (job.status === 'completed') return job as Transcript;
    if (job.status === 'failed') {
      throw new Error(`Job failed: ${JSON.stringify(job.error)}`);
    }
    await sleep(1000); // status checks don't cost credits
  }
  throw new Error(`Job ${jobId} did not finish in time`);
}

export async function getTranscript(videoUrl: string, lang?: string) {
  const params = new URLSearchParams({
    url: videoUrl,
    mode: 'auto', // native captions first, AI generation as fallback
    text: 'false', // timestamped chunks instead of one string
  });
  if (lang) params.set('lang', lang);

  const res = await apiGet(`/transcript?${params}`);
  if (res.status === 202) {
    const { jobId } = (await res.json()) as { jobId: string };
    console.log(`Queued as job ${jobId}, polling...`);
    return waitForJob(jobId);
  }
  // 206 is in the success range but means "transcript-unavailable".
  if (res.status === 206 || !res.ok) await fail(res);
  return (await res.json()) as Transcript;
}

function toTimestamp(ms: number): string {
  const total = Math.floor(ms / 1000);
  const h = String(Math.floor(total / 3600)).padStart(2, '0');
  const m = String(Math.floor((total % 3600) / 60)).padStart(2, '0');
  const s = String(total % 60).padStart(2, '0');
  return `${h}:${m}:${s}`;
}

async function main() {
  const [videoUrl, lang] = process.argv.slice(2);
  if (!API_KEY || !videoUrl) {
    console.error('Usage: SUPADATA_API_KEY=... npx tsx transcript.ts <url> [lang]');
    process.exit(1);
  }

  const transcript = await getTranscript(videoUrl, lang);
  if (transcript.content.length === 0) {
    console.log('No speech detected.');
    return;
  }

  const lines = transcript.content.map(
    (chunk) => `[${toTimestamp(chunk.offset)}] ${chunk.text.trim()}`
  );
  await writeFile('transcript.txt', `${lines.join('\n')}\n`, 'utf8');
  console.log(
    `Saved ${lines.length} lines (${transcript.lang}) to transcript.txt. ` +
      `Other languages: ${transcript.availableLangs.join(', ') || 'none'}`
  );
}

main().catch((error) => {
  console.error(error instanceof Error ? error.message : error);
  process.exit(1);
});

Run it

export SUPADATA_API_KEY="your-key-here"
npx tsx transcript.ts "https://www.tiktok.com/@creator/video/1234567890"

The script writes transcript.txt with one timestamped line per chunk:

[00:00:00] Hello and welcome.
[00:01:01] Today we test transcripts.

Pass a language code as the second argument to prefer a specific language. The response's availableLangs field tells you which other languages exist.

npx tsx transcript.ts "https://www.instagram.com/reel/ABC123/" es

What each part does

  • apiGet sends every request with the x-api-key header. On a 429 it waits for the time in Retry-After when the server sends one, otherwise for 1, 2, 4, 8… seconds (capped at 30), and gives up after five retries. On the free plan's 1 request per second this matters as soon as you loop over several URLs.
  • getTranscript builds the query, returns 200 results directly, and hands 202 responses to waitForJob.
  • waitForJob polls once a second until the job is completed or failed, with a 15-minute safety timeout. Supadata doesn't charge for status checks, but it deletes job results one hour after completion, so read them promptly.
  • fail turns Supadata's error body (error, message) into a readable exception. It also catches 206 transcript-unavailable. Because 206 is a success code, res.ok alone would let it through.

What it costs

From Supadata's documentation at the time of writing:

CaseCost
Existing transcript fetched (native, or auto that finds captions)1 credit
AI-generated transcript (generate, or auto fallback)2 credits per minute of video
206 transcript unavailable1 credit
Polling a jobFree

With mode=auto, a video without captions costs 2 credits per minute. A 10-minute TikTok without captions uses 20 credits, which is a fifth of the free plan's monthly 100. Use mode=native while you are testing if you only want to pay for captions that already exist. You can see the exact charge for each request in the x-billable-requests response header.

Limits to know

  • Public videos only. Private, login-only or region-blocked videos return 403 or 404.
  • No live streams.
  • File URLs must be publicly accessible, and files over 750 MB or 12 hours are rejected.
  • An empty content array means no speech was detected. The request is still billed by duration, so the script reports it instead of writing an empty file.

When you don't want to write code

If you only need a transcript now and then, you don't need an API key. Paste the link into FastScribe's video link to text tool, which runs this same flow. You can then edit the transcript and export it as TXT, DOCX, XLSX or SRT. For files you already have, use audio to text.

Sources

Checked on November 17, 2026: Supadata Get transcript, Errors and Pricing.

Frequently asked questions

How many credits does a Supadata transcript cost?

According to Supadata's documentation, a transcript that already exists on the platform costs 1 credit, and an AI-generated transcript costs 2 credits per minute of video. A 206 transcript-unavailable response costs 1 credit, and checking the status of an async job is free.

Why does the Supadata API return HTTP 202?

For longer videos (Supadata mentions videos over 20 minutes) and some AI-generated transcripts, the API starts a background job and returns a jobId with HTTP 202. Poll GET /v1/transcript/{jobId} about once a second until the status is completed or failed. Results expire one hour after completion.

Which platforms does the Supadata transcript endpoint support?

The documentation lists YouTube, TikTok, Instagram, X (Twitter), Facebook and publicly accessible file URLs. Private or login-only videos return 403 or 404, and live streams are not supported.

Does the free Supadata plan work for this tutorial?

Yes. At the time of writing, Supadata's pricing page lists a free plan with 100 credits per month and a limit of 1 request per second, without a credit card. The retry logic in this example handles the 429 responses you get when you hit that limit.

Newsletter

Join the community

Subscribe to our newsletter for the latest news and updates