Quickstart: extract structured data from video

You need a key from the dashboard and a video whose captions are public. New accounts start with 3,000 credits. A video costs 10 credits per started minute, so that covers about 300 minutes of video, or 23 runs of the 13-minute example below.

A schema is a list of columns, each with a name and a plain-language description. The description is the instruction, so write it the way you would brief a person.

// no SDK needed — plain fetch
const res = await fetch("https://api.tubeextract.dev/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TUBEEXTRACT_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    // always a list — one video here, up to 200 in the same call
    videos: ["https://youtu.be/dQw4w9WgXcQ"],
    multiple: true,
    schema: [
      { name: "city", type: "verbatim-string",
        description: "A city the speaker mentions visiting" },
      { name: "timestamp", type: "string",
        description: "When it is mentioned, as hh:mm:ss" }
    ]
  })
});
 
const job = await res.json(); // 202 Accepted
console.log(job.job_id); // 8f2c1e40-91a3-4b7e

Request body

Extraction is asynchronous, so the submit call answered 202 Accepted with an id rather than rows. A single video usually settles in under a minute. Poll every eight seconds or so. Every call counts against your plan’s per-minute limit, which is 10 on Free and includes the submit, and a 429 tells you how long to wait in Retry-After. On a paid plan you can pass a webhook_url and skip polling entirely.

Each video’s rows stays null until every video in the job has settled, so polling is free and destroys nothing.

A video in a job settles as done or failed, and these are the outcomes you will meet most. The rest of the failure codes are on error codes. A failed HTTP call is a different thing: retry that with the same idempotency key.