JavaScript SDK - VidNavigator API

The official JavaScript and TypeScript SDK for the VidNavigator API. Responses are parsed into typed model classes, and long-running work such as speech-to-text, extraction, tweet analysis and TikTok scraping runs as background jobs, so media of any length works with a single await.

npm package

vidnavigator 2.1.0 on the npm registry.

GitHub repository

Source code, issues and changelog.

This page documents version 2.1.0. Coming from 1.x? See Upgrading from 1.x.

Installation

npm install vidnavigator@2.1.0

yarn add vidnavigator@2.1.0

pnpm add vidnavigator@2.1.0

Requirements: Node.js 16+ (18+ for the examples that use the global fetch). The only runtime dependencies are axios and form-data. Full TypeScript types ship with the package.

The SDK is for server-side use. It reads local files for uploads and schema files, and your API key must never be shipped to a browser.

Initialization

Get your API key in the Developer Dashboard.

import { VidNavigatorClient } from 'vidnavigator';

const vn = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY!,
});

const { VidNavigatorClient } = require('vidnavigator');

const vn = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY,
});

Configuration

Option	Default	Description
`apiKey`	(required)	Your VidNavigator API key
`baseURL`	`https://api.vidnavigator.com/v1`	API base URL
`axiosConfig`		Passed to the underlying axios instance: HTTP timeout, proxy, extra headers, …

const vn = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY!,
  axiosConfig: {
    timeout: 120_000, // per HTTP request, in ms
    proxy: { protocol: 'http', host: 'proxy.internal', port: 3128 },
  },
});

axiosConfig.timeout limits each HTTP request. How long the SDK waits for a background job is set per call with timeoutMs (see Background jobs).

Supported platforms

Platform	Transcript (captions)	Transcribe (speech-to-text)	Carousel
YouTube	Yes	-	-
Instagram Reels	-	Yes	Yes
Instagram Posts	-	Yes	Yes (`all_videos`)
TikTok	Yes	Yes	-
X / Twitter	Yes	Yes	-
Vimeo	Yes	Yes	-
Facebook	Yes	Yes	-
Dailymotion	Yes	Yes	-
Loom	Yes	Yes	-
Uploaded files	Yes	Yes	-

Transcript = fast extraction of the platform’s own captions. Transcribe = speech-to-text by AI models, for when captions are unavailable.

Transcripts

Captions from any platform

getTranscript auto-detects the platform from the URL. Instagram has no captions, so use transcribe for it.

const { video_info, transcript } = await vn.getTranscript({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  language: 'en',
});

console.log(video_info.title);    // "Rick Astley - Never Gonna Give You Up"
console.log(video_info.channel);  // "Rick Astley"
console.log(video_info.duration); // 212

// Timed segments by default (a single string when transcript_text: true)
if (Array.isArray(transcript)) {
  for (const seg of transcript.slice(0, 3)) {
    console.log(`[${seg.start.toFixed(1)}s] ${seg.text}`);
  }
}
// [0.0s] We're no strangers to love
// [3.4s] You know the rules and so do I

Common options: video_url, language, metadata_only, fallback_to_metadata, transcript_text (full transcript as one string), include_usage.

getYouTubeTranscript() still works but is deprecated: it forwards to getTranscript() and logs a warning.

Speech-to-text

vn.transcribe() runs speech-to-text as a background job and resolves with the result, whatever the video length.

// Instagram Reel (speech-to-text only)
const { video_info, transcript } = await vn.transcribe('https://www.instagram.com/reel/C86ZvEaqRmo/');
console.log(video_info.title);
console.log(transcript);

// More options: pass an object instead of a URL
const result = await vn.transcribe(
  { video_url: 'https://www.tiktok.com/@user/video/1234567890', transcript_text: true },
  { include_usage: true }
);
console.log(result.usage?.total_credits);

For TikTok, X, Vimeo, Facebook, Dailymotion and Loom you can use either getTranscript (captions, fast) or transcribe (speech-to-text).

Instagram carousels

Select one video by index, or transcribe every video in the post:

// Transcribe the 2nd video in a carousel
const single = await vn.transcribe('https://www.instagram.com/p/ABC123/?img_index=2');
console.log(single.video_info.carousel_info);
// { total_items: 5, video_count: 3, image_count: 2, selected_index: 2 }

// Transcribe ALL videos in a carousel
const all = await vn.transcribe({
  video_url: 'https://www.instagram.com/p/ABC123/',
  all_videos: true,
});

if ('carousel_info' in all) {
  console.log(`${all.carousel_info.transcribed_count} of ${all.carousel_info.video_count} videos transcribed`);

  for (const video of all.videos) {
    if (video.status === 'success') {
      console.log(`Video #${video.index}: ${video.video_info?.title}`, video.transcript);
    } else {
      console.log(`Video #${video.index}: failed — ${video.message}`);
    }
  }
}

AI analysis

Get a summary, the people, places and key subjects, and a direct answer to a natural-language question. query is optional.

const { video_info, transcript_analysis } = await vn.analyzeVideo({
  video_url: 'https://www.youtube.com/watch?v=4czjS9h4Fpg',
  query: 'Where did the rover land?',
});

console.log(transcript_analysis.summary);
console.log(transcript_analysis.query_answer?.answer);            // direct answer to your question
console.log(transcript_analysis.query_answer?.relevant_segments); // supporting transcript excerpts
console.log(transcript_analysis.people);        // [{ name, context }, ...]
console.log(transcript_analysis.places);
console.log(transcript_analysis.key_subjects);  // [{ name, description, importance }, ...]

const { transcript_analysis } = await vn.analyzeFile({
  file_id: 'your_file_id',
  query: 'What action items were discussed?',
});

console.log(transcript_analysis.summary);
console.log(transcript_analysis.query_answer?.answer);

See the Analyzing Videos guide for billing details.

Structured extraction

Define a schema and get back structured data extracted from any video or file transcript. See the Data Extraction guide for schema design tips.

From an online video

const { data, video_info, usage } = await vn.extractVideoData({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  schema: {
    topic:      { type: 'String', description: 'Main topic of the video' },
    language:   { type: 'String', description: 'Primary spoken language (ISO 639-1)' },
    tone:       { type: 'Enum',   description: 'Overall tone', enum: ['positive', 'negative', 'neutral', 'mixed'] },
    key_quotes: { type: 'Array',  description: 'Top 3 memorable quotes', items: { type: 'String', description: 'A quote' } },
  },
  what_to_extract: 'Determine the topic, language, tone, and notable quotes.',
  include_usage: true,
});

console.log(data);
// { topic: "A classic pop love song", language: "en", tone: "positive", key_quotes: [...] }

console.log(video_info?.title, video_info?.duration); // "Rick Astley - Never Gonna Give You Up" 212

console.log(usage?.analysis_tokens?.total_tokens); // 847
console.log(usage?.total_credits);                 // 2

extractVideoData() runs as a background job, so videos of any length work. With transcribe: true (the default), a video without captions is transcribed first. The result has the extracted data, the video’s video_info (a VideoInfo), and usage when requested. vn.extractVideo() and job.result() on vn.extractVideo.submit() return the same shape.

video_info on extraction results requires 2.1.0. In 2.0.0 it is always undefined.

From an uploaded file

const { data } = await vn.extractFileData({
  file_id: 'your-file-id',
  schema: {
    action_items: { type: 'Array',  description: 'Action items from the meeting', items: { type: 'String', description: 'An action item' } },
    next_meeting: { type: 'String', description: 'When is the next meeting scheduled?' },
    sentiment:    { type: 'Enum',   description: 'Overall meeting mood', enum: ['productive', 'tense', 'casual', 'urgent'] },
  },
});

From a schema file

For larger schemas, pass a JSON or YAML file. It is sent as multipart form-data.

const { data } = await vn.extractVideoData({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  schemaFilePath: './schemas/video-extraction.yaml',
});

Schema rules: every field needs type and description. Supported types are String, Number, Boolean, Integer, Object, Array and Enum. Array fields need items, Object fields list sub-fields in properties (up to 10), and Enum fields list allowed values in enum. At most 10 top-level fields and 3 levels of nesting. An invalid schema is rejected with a BadRequestError before anything runs.

Tweet claim analysis

Pass a tweet ID (not the full URL). Attached media of any length is transcribed, so this also runs as a background job.

const statement = await vn.tweetStatement('1585841080431321088');

console.log(statement.final_statement);     // the core claim, in the author's voice
console.log(statement.detailed_analysis);   // claim, context, evidence and stance
console.log(statement.claim_type, statement.intent, statement.tone, statement.emotion, statement.authority);
console.log(statement.topics, statement.entities);
console.log(statement.tweet_media_summary); // summary of attached video/images, if any

See the Tweet Claim Analysis guide.

Background jobs

Transcription, structured extraction, tweet analysis and TikTok scraping run as background jobs on VidNavigator. The SDK always uses the async endpoints, so video length is never a problem. Each operation comes in two shapes:

Operation	Wait for the result	Start it and come back later
Transcription	`await vn.transcribe(url)`	`await vn.transcribe.submit(url)`
Structured extraction	`await vn.extractVideo({ video_url, schema })`	`await vn.extractVideo.submit({ ... })`
Tweet claim analysis	`await vn.tweetStatement(tweetId)`	`await vn.tweetStatement.submit(tweetId)`
TikTok profile scrape	`await vn.tiktokProfile(profileUrl)`	`await vn.tiktokProfile.submit(profileUrl)`
TikTok keyword search	`await vn.tiktokSearch(query)`	`await vn.tiktokSearch.submit(query)`

The 1.x methods transcribeVideo(), extractVideoData() and getTweetStatement() still work with the same arguments. They are now wrappers around the operations above.

Start many at once

.submit() returns a Job right away. Each job has a task_id, status() (checks once), result() (waits, then returns the result) and wait() (waits, then returns the final task without throwing on failure):

const urls = ['https://www.instagram.com/reel/A/', 'https://www.instagram.com/reel/B/', 'https://vimeo.com/123'];

const jobs = await Promise.all(urls.map((url) => vn.transcribe.submit(url)));
console.log(jobs.map((job) => job.task_id)); // store these if you may need to come back later

const results = await Promise.allSettled(jobs.map((job) => job.result()));
results.forEach((r, i) => console.log(urls[i], r.status === 'fulfilled' ? r.value : r.reason.message));

const job = await vn.extractVideo.submit({
  video_url: 'https://www.facebook.com/watch/?v=1234567890',
  schema: {
    speakers: { type: 'Array',  description: 'Names of everyone who speaks', items: { type: 'String', description: 'A speaker name' } },
    verdict:  { type: 'String', description: 'The final conclusion of the video' },
  },
});

console.log(await job.status()); // 'processing' | 'completed' | 'failed'
const { data } = await job.result();

Come back later

A job keeps running even if your process stops waiting, and its result stays available for 1 hour after it finishes. Keep the task_id and reattach with .resume():

const job = vn.transcribe.resume(savedTaskId);
const result = await job.result();

Timeouts

The one-liners and result() wait up to 30 minutes by default, then throw a TaskTimeoutError that carries the task_id. The job is not lost:

import { TaskTimeoutError } from 'vidnavigator';

try {
  const result = await vn.transcribe(url, { timeoutMs: 5 * 60 * 1000 });
} catch (err) {
  if (err instanceof TaskTimeoutError) {
    saveForLater(err.task_id); // later: await vn.transcribe.resume(err.task_id).result()
  } else {
    throw err;
  }
}

Waiting options

Pass these to the one-liner or to result() / wait():

Option	Default	Description
`timeoutMs`	30 minutes	Stop waiting and throw `TaskTimeoutError` (with `task_id`). `0` waits forever
`intervalMs`	`3000`	Time between checks. Checking costs no credits and is not rate-limited
`fastStart`	`true`	Check every second for the first 10 seconds, so short clips return quickly
`signal`		An `AbortSignal` to stop waiting early (the job keeps running)
`onPoll`		Called with each task snapshot, e.g. for progress logs
`include_usage`	`false`	Attach a `usage` block to the result (one-liner, `.submit()` and `.resume()` options)

Job members

Member	Description
`.submit(input, { include_usage? })`	Start the job and return a `Job` immediately
`.resume(task_id, { include_usage? })`	Get a `Job` for a job you already started (no request is made)
`job.task_id`, `job.job_type`, `job.check_status_url`, `job.webhook_url`	Job details from the submit response
`job.status()`	Check once; returns `'processing'`, `'completed'` or `'failed'`
`job.refresh()`	Check once; returns the full task (`error`, `webhook`, timestamps, …)
`job.result(options?)`	Wait until finished and return the result. Throws on failure or timeout; every error carries `task_id`
`job.wait(options?)`	Wait until finished and return the final task, without throwing on failure

Result types

transcribe → same shape as transcribeVideo(); extractVideo → { data, video_info, usage? }; tweetStatement → TweetStatement; tiktokProfile / tiktokSearch → the completed task with every page of videos / results.

Failures

When a job fails, result() and the one-liners throw the same error class as any other API error (for example NotFoundError for a missing video), built from the job’s error details and carrying the task_id. wait() returns the failed task instead, with task.error set. When a job can’t start, submitting throws right away and no job is created:

InsufficientCreditsError (402): not enough credits. A job can also run out of credits while it runs; result() then throws the same error, so handle it in both places.
TooManyActiveJobsError (429): too many of your jobs are already running. Wait for some to finish and retry.

Large batches

Your account can only run a limited number of jobs at once, so Promise.all over hundreds of URLs will hit TooManyActiveJobsError. Keep a fixed number in flight:

import { TooManyActiveJobsError } from 'vidnavigator';

async function transcribeAll(urls: string[], concurrency = 10) {
  const results = new Map<string, unknown>();
  const queue = [...urls];

  async function worker() {
    for (let url = queue.shift(); url; url = queue.shift()) {
      for (;;) {
        try {
          results.set(url, await vn.transcribe(url));
          break;
        } catch (err) {
          if (err instanceof TooManyActiveJobsError) {
            await new Promise((r) => setTimeout(r, 10_000)); // wait for running jobs to finish
            continue;
          }
          results.set(url, err); // record the failure and move on
          break;
        }
      }
    }
  }

  await Promise.all(Array.from({ length: concurrency }, worker));
  return results;
}

Progress and restarts

// Log every task snapshot while waiting
const started = Date.now();
const result = await vn.transcribe(url, {
  onPoll: (task) => console.log(`${task.task_id}: ${task.task_status} after ${Math.round((Date.now() - started) / 1000)}s`),
});

Save each task_id as soon as you submit, so a crash or deploy doesn’t lose the work:

import { writeFileSync, readFileSync, existsSync } from 'fs';

const job = await vn.transcribe.submit(url);
writeFileSync('pending-jobs.json', JSON.stringify([...pending(), job.task_id]));

// After a restart: pick every job back up
for (const taskId of pending()) {
  const result = await vn.transcribe.resume(taskId).result();
  // ... store the result, then drop taskId from pending-jobs.json
}

function pending(): string[] {
  return existsSync('pending-jobs.json') ? JSON.parse(readFileSync('pending-jobs.json', 'utf8')) : [];
}

Webhooks

Pass webhook_url to any job operation (transcription, extraction, tweet analysis, TikTok profile and search), or set an account-wide default in Studio → API. A per-job webhook_url overrides the default, and webhook_url: '' turns it off for one job. Webhooks are optional: waiting with result() works the same either way and remains the source of truth.

const job = await vn.transcribe.submit({
  video_url: 'https://www.instagram.com/reel/C86ZvEaqRmo/',
  webhook_url: 'https://example.com/hooks/vidnavigator',
});
console.log(job.webhook_url); // where the notification will be sent, or null

Verify each delivery with constructWebhookEvent(), passing the raw request body:

import express from 'express';
import { VidNavigatorClient, constructWebhookEvent, WebhookSignatureError, WEBHOOK_HEADERS } from 'vidnavigator';

const vn = new VidNavigatorClient({ apiKey: process.env.VIDNAVIGATOR_API_KEY! });
const app = express();

app.post('/hooks/vidnavigator', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = constructWebhookEvent(
      req.body,                               // raw Buffer, not parsed JSON
      req.headers[WEBHOOK_HEADERS.signature], // "t=<unix_ts>,v1=<hex>"
      process.env.VIDNAVIGATOR_WEBHOOK_SECRET!
    );
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.status(400).send('Invalid signature');
    throw err;
  }
  res.sendStatus(200); // acknowledge quickly; any 2xx counts

  // Deliveries can repeat: dedupe on req.headers[WEBHOOK_HEADERS.delivery].
  if (event.type === 'transcribe.completed') {
    const result = await vn.transcribe.resume(event.data.task_id).result();
    console.log(result);
  } else if (event.type === 'tiktok_profile.completed') {
    const task = await vn.tiktokProfile.resume(event.data.task_id).result(); // every video, all pages
    console.log(task.videos.length);
  } else if (event.type.endsWith('.failed')) {
    console.error(event.data.task_id, event.data.error); // { error, message, http_status }
  }
});

event.data.result holds the raw result for transcription, extraction and tweet events, unless it was over 256 KB (result_truncated: true). For TikTok events it is only a summary. resume(task_id).result() always gets the full parsed result.
For extract_video.completed events, event.data.video_info holds the raw video metadata. It is sent even when the result was truncated.
verifyWebhookSignature(rawBody, signatureHeader, secret) returns true or false instead of throwing.
Deliveries older than 5 minutes are rejected by default. Change this with { toleranceSeconds }; 0 turns the check off.
(await job.refresh()).webhook shows the delivery status: { status, attempts, response_status, last_error, delivered_at }.

See Webhooks for the full delivery contract.

TikTok

Profile scraping

vn.tiktokProfile() scrapes a public profile in the background and returns the finished task with every matching video (the SDK fetches all result pages for you):

const task = await vn.tiktokProfile({
  profile_url: 'https://www.tiktok.com/@tiktok',
  max_posts: 250,
  after_datetime: '2024-01-01',
});

console.log(`Matched ${task.videos.length} videos`, task.stats);
const videos = task.videos; // TikTokVideo[], published_at parsed as Date

Options: max_posts, after_datetime, before_datetime, min_likes, max_likes, webhook_url. Datetimes accept YYYY-MM-DD or full ISO strings with a timezone. To read the results one page at a time, or grab them as a single JSON file, submit the job and use the page-level method:

const job = await vn.tiktokProfile.submit('https://www.tiktok.com/@tiktok');
await job.wait();

// Page by page
let cursor: string | undefined;
do {
  const page = await vn.getTikTokProfileScrape(job.task_id, { limit: 100, cursor });
  handle(page.videos);
  cursor = page.pagination?.next_cursor ?? undefined;
} while (cursor);

// Or the whole result as one JSON file (short-lived signed URL)
const { download_url } = await vn.getTikTokProfileScrape(job.task_id, { limit: 1 });
if (download_url) {
  const fullProfile = await (await fetch(download_url)).json();
  console.log(fullProfile.videos.length);
}

Then feed each video into the transcript or extraction APIs:

for (const video of videos) {
  if (!video.url) continue;

  const { transcript } = await vn.getTranscript({
    video_url: video.url,
    transcript_text: true,
    fallback_to_metadata: true,
  });
  console.log(video.published_at?.toISOString(), video.title, transcript);
}

For large profiles, process videos sequentially or with a small concurrency limit so you do not exhaust credits or hit rate limits.

Keyword search

vn.tiktokSearch() works the same way and returns the finished task with every result:

const task = await vn.tiktokSearch({
  query: 'ai tools',
  max_results: 100,
  sort_by: 'most_liked',          // 'relevance' | 'most_liked' | 'newest'
  published_within: 'this_month', // 'all' | 'past_24_hours' | 'this_week' | 'this_month' | 'last_3_months' | 'last_6_months'
  min_views: 10000,
});

console.log(task.stats?.sort_by, task.stats?.published_within); // what the search actually ran with
for (const result of task.results) {
  console.log(result.published_at?.toISOString(), result.url, result.stats?.views);
}

Without sort_by, results come back newest first. Without published_within, an after_datetime more than 24 hours ago picks the smallest window that covers it.
parallel_search_slices (2 to 4) runs several search chains in parallel to go past TikTok’s single-chain limit (about 115 to 140 items). Billing grows with the number of slices.
Other filters: after_datetime, before_datetime, min_likes, max_likes, min_views, max_views, webhook_url. Page through results with getTikTokSearch(task_id, { cursor, limit }).

See the Searching TikTok guide.

Search

Search YouTube

const videoResults = await vn.searchYouTube({
  query: 'how to deploy a Node.js app',
  focus: 'relevance',   // 'relevance' (default) | 'popularity' | 'brevity'
  max_results: 5,       // caps how many candidates are analysed (and the cost)
  include_usage: true,
});

console.log(`Found ${videoResults.total_found} results`);
for (const r of videoResults.results) {
  console.log(`${r.title} — score: ${r.relevance_score}`);
  console.log(`  ${r.transcript_summary}`);
}

// If credits run out mid-search, a partial result is returned instead of throwing
if (videoResults.status === 'partial') {
  console.log('Partial results:', videoResults.error_code); // "insufficient_credits_video_search"
}

Other options: use_enhanced_search (default true), start_year, end_year, duration.

searchVideos() still works but is deprecated: it forwards to searchYouTube() and logs a warning.

Search your uploaded files

const fileResults = await vn.searchFiles({
  query: 'quarterly revenue discussion',
  namespace_ids: ['ns_finance'], // optional: scope to namespaces
});

for (const r of fileResults.results) {
  console.log(`${r.name} (score: ${r.relevance_score})`);
  console.log(`  Answer: ${r.query_answer}`);
  console.log(`  Namespaces: ${r.namespaces?.map((n) => n.name).join(', ')}`);
}

Files

Supported formats: mp4, webm, mov, avi, wmv, flv, mkv, m4a, mp3, mpeg, mpga, wav.

Upload and analyze

const upload = await vn.uploadFile({
  filePath: './meeting-recording.mp4',
  wait_for_completion: true,
  namespace_ids: ['ns_meetings'], // optional
});

console.log(upload.file_id);                  // "64a1b2c3d4e5f6789..."
console.log(upload.file_info?.namespace_ids); // ["ns_meetings"]

const { transcript_analysis } = await vn.analyzeFile({
  file_id: upload.file_id,
  query: 'What action items were discussed?',
});
console.log(transcript_analysis.query_answer?.answer);

Upload without waiting

Without wait_for_completion, the upload returns right away (status: 'accepted') while the file is processed. Check on it with getFile():

const { file_id } = await vn.uploadFile({ filePath: './interview.mp3' });

let { file_info } = await vn.getFile(file_id);
while (file_info.status === 'processing') {
  await new Promise((r) => setTimeout(r, 5000));
  ({ file_info } = await vn.getFile(file_id));
}

if (file_info.status === 'failed') {
  await vn.retryFileProcessing(file_id); // or cancelFileUpload(file_id) while it is still processing
}

Manage files

const { transcript } = await vn.getFile(file_id, { transcript_text: true }); // full text
const { file_url } = await vn.getFileUrl(file_id);                           // signed URL to view or download
const { files, has_more } = await vn.getFiles({ status: 'completed', limit: 20, offset: 0 });
await vn.deleteFile(file_id);

Namespaces

const ns = await vn.createNamespace({ name: 'Client Calls' });

const updated = await vn.updateFileNamespaces(fileId, { namespace_ids: [ns.id!] });
console.log(updated.namespaces); // [{ id: "...", name: "Client Calls" }]

const files = await vn.getFiles({ namespace_id: ns.id! });
const all = await vn.getNamespaces();

await vn.updateNamespace(ns.id!, { name: 'Sales Calls' });
await vn.deleteNamespace(ns.id!);

Usage and billing

Per-call usage

Pass include_usage: true to getTranscript, analyzeVideo, analyzeFile, extractVideoData, extractFileData, searchYouTube or searchFiles to receive a usage block describing what the request cost. For background jobs, pass it in the options: vn.transcribe(url, { include_usage: true }). A failed job has all its charges reverted.

const { usage } = await vn.getTranscript({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  include_usage: true,
});

if (usage) {
  console.log(usage.total_credits);           // net credits deducted by this request
  console.log(usage.credits_remaining_after); // balance after the request (when provided)

  for (const charge of usage.charges) {
    console.log(charge.service_type, charge.quantity, charge.credits, charge.waived);
  }

  const residential = usage.charge_for('residential_request'); // matching charge or undefined
  console.log(usage.analysis_tokens?.total_tokens);            // LLM tokens (analyze / extract / search)
}

Meters: standard_request, residential_request, transcription_hour, analysis_request, search_request, scene_analysis_hour. See Usage & Costs.

Account usage

const usage = await vn.getUsage();

console.log(`Credits remaining: ${usage.credits.monthly_remaining}`);
console.log(`Transcription hours used: ${usage.usage.transcriptionHour?.used}`);
console.log(`Storage: ${usage.storage.usedFormatted} / ${usage.storage.limitFormatted}`);

vn.healthCheck() returns the API status and needs no authentication.

Error handling

Every API error is mapped to a specific class, all extending VidNavigatorError:

import { AuthenticationError, NotFoundError, RateLimitExceededError, VidNavigatorError } from 'vidnavigator';

try {
  await vn.getFile('nonexistent-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(error.status_code);   // 404
    console.log(error.error_message); // "File not found"
  } else if (error instanceof RateLimitExceededError) {
    console.log('Slow down! Rate limited.');
  } else if (error instanceof VidNavigatorError) {
    console.log(error.error_code, error.message);
  } else {
    throw error;
  }
}

Error class	HTTP	When
`BadRequestError`	400	Invalid parameters
`AuthenticationError`	401	Invalid or missing API key
`PaymentRequiredError`	402	Credit limit reached
`InsufficientCreditsError`	402	A job could not start: not enough credits. Extends `PaymentRequiredError`
`AccessDeniedError`	403	Insufficient permissions
`NotFoundError`	404	Resource does not exist, or a job’s `task_id` is unknown or expired
`StorageQuotaExceededError`	413	Storage quota exceeded
`RateLimitExceededError`	429	Too many requests
`TooManyActiveJobsError`	429	A job could not start: too many jobs already running. Extends `RateLimitExceededError`
`GeoRestrictedError`	451	Content unavailable in your region
`ServerError`	5xx	Unexpected server error
`SystemOverloadError`	503	Temporary overload (has `retry_after_seconds`)
`TaskTimeoutError`	-	Waiting for a job took longer than `timeoutMs`. Has `task_id`; the job keeps running
`WebhookSignatureError`	-	`constructWebhookEvent()` got a missing, invalid or expired signature

Every error exposes status_code, error_code, error_message and details, and errors raised while waiting for a job also have task_id. See Errors for every API error code.

TypeScript models

All API responses are parsed into typed classes with static fromJSON() constructors.

Videos, files and analysis

Class	Description
`VideoInfo`	Video metadata: title, channel, duration, views, likes, published date, keywords, carousel info
`FileInfo`	Uploaded file: name, size, type, duration, status, `namespace_ids`, `namespaces`
`TranscriptSegment`	Timed segment: `text`, `start`, `end` (seconds)
`AnalysisResult`	AI analysis: summary, people, places, key subjects, query answer
`CarouselInfo`	Carousel summary: total items, video/image count, transcribed count, total duration
`CarouselVideoResult`	Per-video result in a carousel: index, status, video info, transcript
`TweetStatement`	Structured X/Twitter claim analysis, topics, entities, tone, intent and source text

Search and namespaces

Class	Description
`VideoSearchResult`	Extends `VideoInfo` with `relevance_score`, `transcript_summary` and search metadata
`FileSearchResult`	Extends `FileInfo` with `relevance_score`, `query_answer`, timestamps and a signed URL
`Namespace`	Full namespace: id, name, created/updated timestamps
`NamespaceRef`	Lightweight `{ id, name }` reference embedded in file and search responses

Jobs and TikTok

Class	Description
`Job`	Handle returned by `.submit()` / `.resume()`: `task_id`, `status()`, `refresh()`, `result()`, `wait()`
`AsyncJob<T>`	Task snapshot of a transcription, extraction or tweet job: `task_status`, `result`, `video_info` (extraction jobs), `error`, `webhook`, `request`, timestamps
`TikTokProfileTask`	Profile scrape task: status, profile metadata, videos, pagination, `download_url`, `error`, `webhook`
`TikTokVideo`	Public TikTok video metadata, with `published_at` as a `Date` and integer counters
`TikTokSearchTask`	Keyword search task: status, results, pagination, `download_url`; `stats` shows the `sort_by` / `published_within` used
`TikTokSearchResult`	Normalized keyword result, with `published_at` as a `Date` and integer counters

Usage

Class	Description
`UsageData`	Account usage from `getUsage()`: credits, per-service activity, storage, subscription
`UsageBlock`	Per-call usage: `charges[]`, `total_credits`, `credits_remaining_after`, `waived`, plus `charge_for()` and `analysis_tokens`
`UsageCharge`	One meter charge: `service_type`, `quantity`, `credits`, `waived`, `credits_saved`, and `tokens` on `analysis_request`

What’s new in 2.1.0

video_info on extraction: extractVideoData(), vn.extractVideo() and job.result() on vn.extractVideo.submit() now return the video’s metadata as video_info. The task snapshot from job.refresh() / job.wait() has it too, and extract_video.completed webhook events carry it in event.data.video_info.

No other changes are needed to upgrade from 2.0.0.

Upgrading from 1.x

Transcription, structured extraction and tweet analysis now always run as background jobs, so they work on videos of any length. Existing calls keep working with the same arguments, with these differences:

getTweetStatement() no longer returns statement_query, which was never part of the documented API.
searchVideos() and getYouTubeTranscript() are deprecated in favor of searchYouTube() and getTranscript().

New in 2.0: vn.transcribe, vn.extractVideo, vn.tweetStatement, vn.tiktokProfile and vn.tiktokSearch, each with .submit() and .resume(), plus the webhook signature helpers and the InsufficientCreditsError, TooManyActiveJobsError and TaskTimeoutError classes.

Resources

npm

Package page and release history.

GitHub

Source code and issue tracker.

Python SDK

The same API for Python.

API Reference

Every endpoint, parameter and response field.

npm package

GitHub repository

​Installation

​Initialization

​Configuration

​Supported platforms

​Transcripts

​Captions from any platform

​Speech-to-text

​Instagram carousels

​AI analysis

​Structured extraction

​From an online video

​From an uploaded file

​From a schema file

​Tweet claim analysis

​Background jobs

​Start many at once

​Come back later

​Timeouts

​Failures

​Large batches

​Progress and restarts

​Webhooks

​TikTok

​Profile scraping

​Keyword search

​Search

​Search YouTube

​Search your uploaded files

​Files

​Upload and analyze

​Upload without waiting

​Manage files

​Namespaces

​Usage and billing

​Per-call usage

​Account usage

​Error handling

​TypeScript models

​What’s new in 2.1.0

​Upgrading from 1.x

​Resources

npm

GitHub

Python SDK

API Reference

Installation

Initialization

Configuration

Supported platforms

Transcripts

Captions from any platform

Speech-to-text

Instagram carousels

AI analysis

Structured extraction

From an online video

From an uploaded file

From a schema file

Tweet claim analysis

Background jobs

Start many at once

Come back later

Timeouts

Failures

Large batches

Progress and restarts

Webhooks

TikTok

Profile scraping

Keyword search

Search

Search YouTube

Search your uploaded files

Files

Upload and analyze

Upload without waiting

Manage files

Namespaces

Usage and billing

Per-call usage

Account usage

Error handling

TypeScript models

What’s new in 2.1.0

Upgrading from 1.x

Resources