Supadata JS SDK

https://github.com/supadata-ai/js
Admin
Supadata JS SDK is the official TypeScript and JavaScript SDK for the Supadata API, enabling...
Tokens:30,699
Snippets:226
Trust Score:4.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://github.com/supadata-ai/js/blob/main/example/README.md

Run this command in the example directory to install the required npm packages.

```bash
cd example
npm install
```

--------------------------------

### Run the example

Source: https://github.com/supadata-ai/js/blob/main/example/README.md

Starts the example after replacing YOUR_API_KEY in index.ts with your Supadata API key.

```bash
npm start
```

--------------------------------

### get Method Example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Example of using the get method to fetch a transcript, handling both direct and job-based responses.

```APIDOC
const result = await supadata.transcript({
  url: 'https://www.example.com/video',
});

if ('jobId' in result) {
  console.log(`Large video — job ${result.jobId} started`);
} else {
  console.log(result.content, result.availableLangs);
}
```

--------------------------------

### Usage example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Example usage of fetching a single transcript and starting a batch job.

```typescript
const youTubeTranscript = await supadata.youtube.transcript({
  videoId: 'dQw4w9WgXcQ',
  lang: 'en',
  text: true,
});
console.log(youTubeTranscript.content);

const batchJob = await supadata.youtube.transcript.batch({
  videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'],
  lang: 'en',
});
console.log(`Batch job: ${batchJob.jobId}`);
```

--------------------------------

### Example — handling both outcomes

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Example of handling both outcomes from the get method.

```typescript
const result = await supadata.transcript({
  url: 'https://www.youtube.com/watch?v=...',
});

if ('jobId' in result) {
  console.log(`Large video — job ${result.jobId} started`);
} else {
  console.log(result.content, result.availableLangs);
}
```

--------------------------------

### Installation

Source: https://github.com/supadata-ai/js/blob/main/README.md

Install the Supadata JS SDK via npm.

```bash
npm install @supadata/js
```

--------------------------------

### Prompt-driven extraction example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Example of starting an extraction job using a prompt. The API generates a JSON schema automatically when prompt is used alone.

```typescript
const job = await supadata.extract({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  prompt: 'Extract the main topics and key takeaways',
});
console.log(`Started extract job: ${job.jobId}`);
```

--------------------------------

### Supadata Configuration Examples

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/configuration.md

Configuration examples for the Supadata JavaScript SDK.

```typescript
export interface SupadataConfig {
  apiKey: string;
  baseUrl?: string;
}
```

```typescript
import { Supadata } from '@supadata/js';

const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});
```

```typescript
const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://your-proxy.example.com',
});
```

--------------------------------

### Schema-driven extraction example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Example of starting an extraction job with a JSON schema for structured output, guaranteeing field shapes.

```typescript
const { jobId } = await supadata.extract({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  schema: {
    type: 'object',
    properties: {
      topics: { type: 'array', items: { type: 'string' } },
      summary: { type: 'string' },
    },
    required: ['topics', 'summary'],
  },
});
```

--------------------------------

### extract job lifecycle example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata.md

Example showing the full job lifecycle: start an extraction job with a prompt, then poll for results using getResults. Handles completed and failed statuses.

```typescript
const job = await supadata.extract({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  prompt: 'Extract the main topics and key takeaways',
});

const result = await supadata.extract.getResults(job.jobId);
if (result.status === 'completed') {
  console.log('Extracted data:', result.data);
  console.log('AI-generated schema:', result.schema);
} else if (result.status === 'failed') {
  console.error(result.error?.message);
}
```

--------------------------------

### GET request to /v1/youtube/transcript

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Example HTTP GET request to the Supadata API for fetching a YouTube transcript.

```text
GET https://api.supadata.ai/v1/youtube/transcript?videoId=dQw4w9WgXcQ&lang=en
x-api-key: <key>
Content-Type: application/json
User-Agent: supadata-js/1.4.0
```

--------------------------------

### fetch Usage Example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/base-client.md

Example usage of the fetch method as used by subclasses.

```typescript
// Used internally by WebService.map — equivalent of:
return this.fetch<SiteMap>('/web/map', { url });
```

--------------------------------

### metadata example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata.md

Example usage of the metadata method. It retrieves metadata for a YouTube video and logs the platform, view count, and tags.

```typescript
const meta = await supadata.metadata({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
});

console.log(meta.platform); // 'youtube'
console.log(meta.stats.views, meta.tags);
```

--------------------------------

### getJobStatus Example with Polling

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Example of polling the job status with error handling.

```APIDOC
import { Supadata, SupadataError } from '@supadata/js';

const supadata = new Supadata({ apiKey: 'YOUR_API_KEY' });
const res = await supadata.transcript({ url: 'https://example.com/big.mp4' });

try {
  const job = await supadata.transcript.getJobStatus(
    res.jobId, // only valid when a JobId was returned
  );
  if (job.status === 'completed') {
    console.log(job.result);
  }
} catch (e) {
  if (e instanceof SupadataError) console.error(e.error, e.message);
}
```

--------------------------------

### Run SDK in watch mode

Source: https://github.com/supadata-ai/js/blob/main/example/README.md

Starts the SDK in watch mode for development.

```bash
npm run dev
```

--------------------------------

### Supadata API Usage Examples

Source: https://github.com/supadata-ai/js/blob/main/README.md

Code examples for the Supadata API covering YouTube and Web endpoints.

```APIDOC
### YouTube

```typescript
// Translate YouTube transcript
const translated: Transcript = await supadata.youtube.translate({
  videoId: 'dQw4w9WcXgQ',
  lang: 'es',
});

// Get a YouTube channel metadata
const channel: YoutubeChannel = await supadata.youtube.channel({
  id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle
});

// Get a list of video IDs from a YouTube channel
const channelVideos: VideoIds = await supadata.youtube.channel.videos({
  id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle
  limit: 10,
});

// Get the metadata of a YouTube playlist
const playlist: YoutubePlaylist = await supadata.youtube.playlist({
  id: 'https://youtube.com/playlist?list=PL...', // can be url or playlist id
});

// Start a YouTube video metadata batch job
const videoBatch = await supadata.youtube.video.batch({
  videoIds: ['dQw4w9WcXgQ', 'dQw4w9WcXgQ'],
});

// Get results for a batch job (poll until status is 'completed' or 'failed')
const batchResults = await supadata.youtube.batch.getBatchResults(
  videoBatch.jobId
);
if (batchResults.status === 'completed') {
  console.log('Batch job completed:', batchResults.results);
  console.log('Stats:', batchResults.stats);
} else {
  console.log('Batch job status:', batchResults.status);
}

// Search YouTube for videos, channels, and playlists
const searchResults = await supadata.youtube.search({
  query: 'never gonna give you up',
  type: 'video', // optional: 'all', 'video', 'channel', 'playlist'
  limit: 10, // optional: max results (1-5000)
  nextPageToken: '...', // optional: for pagination
});

// Search for channels
const channelSearch = await supadata.youtube.search({
  query: 'fireship',
  type: 'channel',
  limit: 5,
});

// Search for playlists
const playlistSearch = await supadata.youtube.search({
  query: 'javascript tutorials',
  type: 'playlist',
  limit: 10,
});
```

### Web

```typescript
// Scrape web content
const webContent: Scrape = await supadata.web.scrape('https://supadata.ai');

// Map website URLs
const siteMap: Map = await supadata.web.map('https://supadata.ai');

// Crawl website
const crawl: JobId = await supadata.web.crawl({
  url: 'https://supadata.ai',
  limit: 10,
});

// Get crawl job results
const crawlResults: CrawlJob = await supadata.web.getCrawlResults(crawl.jobId);
```
```

--------------------------------

### batch.getBatchResults

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Code examples for the batch.getBatchResults method, including the method definition and a usage example.

```typescript
batch = {
  getBatchResults: async (jobId: string): Promise<YoutubeBatchResults> => {
    if (!jobId) {
      throw new SupadataError({
        error: 'invalid-request',
        message: 'Missing jobId',
        details: 'The jobId parameter is required to get batch results.',
      });
    }
    return this.fetch<YoutubeBatchResults>(`/youtube/batch/${jobId}`);
  },
};
```

```typescript
const results = await supadata.youtube.batch.getBatchResults(batchJob.jobId);
if (results.status === 'completed') {
  console.log(results.results, results.stats); // per-video transcripts + totals
}
```

--------------------------------

### Instantiate Supadata client

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata.md

Example of instantiating the Supadata client with an API key and optional baseUrl override.

```typescript
import { Supadata } from '@supadata/js';

const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY', // required — get one at https://supadata.ai
  baseUrl: 'https://api.supadata.ai/v1', // optional — overrides the default endpoint
});
```

--------------------------------

### Error handling example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/base-client.md

Example of error handling in a consumer, demonstrating how to catch and inspect SupadataError instances.

```typescript
import { Supadata, SupadataError } from '@supadata/js';

const supadata = new Supadata({ apiKey: process.env.SUPADATA_API_KEY! });

try {
  const meta = await supadata.metadata({ url: 'https://bad-url' });
  console.log(meta);
} catch (e) {
  if (e instanceof SupadataError) {
    // error: 'invalid-request' | 'internal-error' | 'unauthorized' | ...
    console.error(e.error, '—', e.message, e.details, e.documentationUrl);
  }
}
```

--------------------------------

### Example - error handling

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Example demonstrating error handling for getResults. Shows local validation error when jobId is empty and API 404 error for unknown job IDs.

```typescript
try {
  const missing = await supadata.extract.getResults(''); // throws locally
} catch (e) {
  if (e instanceof SupadataError) {
    console.error(e.error);   // 'invalid-request'
    console.error(e.message); // 'Missing jobId'
  }
}

try {
  await supadata.extract.getResults('unknown-job-id'); // API 404 -> SupadataError
} catch (e) {
  if (e instanceof SupadataError && e.error === 'not-found') {
    console.error('Job not found:', e.message);
  }
}
```

--------------------------------

### translate

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Code examples for the translate method, including the method definition and a usage example.

```typescript
translate = async (params: TranslateParams): Promise<TranslatedTranscript> => {
  return this.fetch<TranslatedTranscript>(
    '/youtube/transcript/translate',
    params
  );
};
```

```typescript
const translated = await supadata.youtube.translate({
  videoId: 'dQw4w9WgXcQ',
  lang: 'es',
});
console.log(translated.lang, translated.content);
```

--------------------------------

### scrape example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Example usage of supadata.web.scrape to scrape a page and log its name, content, and character count.

```typescript
const page = await supadata.web.scrape('https://supadata.ai');
console.log(page.name, page.content, page.countCharacters);
```

--------------------------------

### Poll a crawl job and process results

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Starts a crawl with a limit of 2, then retrieves results using getCrawlResults. The method auto-paginates internally; the example checks for completion and logs each page's URL and content length.

```typescript
const crawl = await supadata.web.crawl({ url: 'https://supadata.ai', limit: 2 });

// Wait for the crawl to progress, then fetch results (auto-paginated)
const results = await supadata.web.getCrawlResults(crawl.jobId);
if (results.status === 'completed') {
  console.log(`Crawled ${results.pages?.length} pages`);
  for (const page of results.pages ?? []) {
    console.log(page.url, page.content.length);
  }
}
```

--------------------------------

### get Method Signature

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Method signature for the get method.

```typescript
get = async (params: GeneralTranscriptParams): Promise<TranscriptOrJobId>
```

--------------------------------

### ExtractService.get method signature

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Method signature for the get method, which starts an asynchronous extraction job.

```typescript
get = async (params: ExtractParams): Promise<JobId>
```

--------------------------------

### Example — discriminating TranscriptOrJobId

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata.md

Example showing how to handle the TranscriptOrJobId union type.

```typescript
const result = await supadata.transcript({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  lang: 'en',
  text: true,
  mode: 'auto', // 'native' | 'auto' | 'generate'
});

if ('jobId' in result) {
  // Large video — poll for the job result
  const job = await supadata.transcript.getJobStatus(result.jobId);
  if (job.status === 'completed') {
    console.log(job.result?.content);
  } else if (job.status === 'failed') {
    console.error(job.error);
  }
} else {
  console.log(result.content); // Transcript returned inline
}
```

--------------------------------

### Example — polling with error handling

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Example of polling job status with error handling.

```typescript
import { Supadata, SupadataError } from '@supadata/js';

const supadata = new Supadata({ apiKey: 'YOUR_API_KEY' });
const res = await supadata.transcript({ url: 'https://example.com/big.mp4' });

try {
  const job = await supadata.transcript.getJobStatus(
    res.jobId, // only valid when a JobId was returned
  );
  if (job.status === 'completed') {
    console.log(job.result?.content);
  } else if (job.status === 'failed') {
    console.error(job.error?.error, job.error?.details);
  }
} catch (e) {
  if (e instanceof SupadataError) console.error(e.error, e.message);
}
```

--------------------------------

### Example - poll until terminal state

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Example showing how to poll the getResults method until the job reaches a terminal state (completed or failed). Uses a 3-second delay between polls.

```typescript
import { Supadata, SupadataError } from '@supadata/js';

const supadata = new Supadata({ apiKey: 'YOUR_API_KEY' });
const job = await supadata.extract({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  prompt: 'List all products mentioned',
});

let result;
while (true) {
  result = await supadata.extract.getResults(job.jobId);
  if (result.status === 'completed' || result.status === 'failed') break;
  await new Promise((r) => setTimeout(r, 3000)); // 'queued' / 'active' — poll again
}

if (result.status === 'completed') {
  console.log('Data:', result.data);
  console.log('Schema used:', result.schema);
} else {
  console.error('Extract failed:', result.error?.message);
}
```

--------------------------------

### Advanced Search with Pagination

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Example of an advanced search with pagination, using filters and fetching the next page if a token exists.

```typescript
const page1 = await supadata.youtube.search({
  query: 'javascript tutorials',
  type: 'video',
  uploadDate: 'month',
  duration: 'medium',
  sortBy: 'views',
  features: ['hd'],
  limit: 10,
});

if (page1.nextPageToken) {
  const page2 = await supadata.youtube.search({
    query: 'javascript tutorials',
    type: 'video',
    nextPageToken: page1.nextPageToken,
  });
  console.log(page2.results);
}
```

--------------------------------

### Constructing SupadataError Directly

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata-error.md

Example of constructing a SupadataError directly, as the SDK does internally.

```typescript
throw new SupadataError({
  error: 'invalid-request',
  message: 'Missing jobId',
  details: 'The jobId parameter is required to get transcript job status.',
});
```

--------------------------------

### Start a crawl job with supadata.web.crawl

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Initiates an asynchronous crawl job with a URL and a limit of 10 pages. Returns a jobId for later retrieval.

```typescript
const crawl = await supadata.web.crawl({
  url: 'https://supadata.ai',
  limit: 10,
});
console.log(`Crawl job started: ${crawl.jobId}`);
```

--------------------------------

### ExtractService class declaration

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Full class declaration for ExtractService, extending BaseClient. The get method starts an extraction job via POST /extract, and getResults fetches results by jobId, throwing a SupadataError if jobId is missing.

```typescript
export class ExtractService extends BaseClient {
  get = async (params: ExtractParams): Promise<JobId> => {
    return this.fetch<JobId>('/extract', params, 'POST');
  };

  getResults = async (jobId: string): Promise<ExtractJobResult> => {
    if (!jobId) {
      throw new SupadataError({
        error: 'invalid-request',
        message: 'Missing jobId',
        details:
          'The jobId parameter is required to get extract job results.',
      });
    }
    return this.fetch<ExtractJobResult>(`/extract/${jobId}`);
  };
}
```

--------------------------------

### getJobStatus Missing jobId Example

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Example of missing jobId validation.

```APIDOC
try {
  await supadata.transcript.getJobStatus('');
} catch (e) {
  if (e instanceof SupadataError) console.error(e.error, e.message);
}
```

--------------------------------

### Catch a SupadataError

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata-error.md

Example showing how to catch and inspect a SupadataError thrown by an SDK method like supadata.youtube.transcript().

```typescript
import { Supadata, SupadataError } from '@supadata/js';

const supadata = new Supadata({ apiKey: 'YOUR_API_KEY' });

try {
  await supadata.youtube.transcript({ videoId: 'INVALID_ID' });
} catch (e) {
  if (e instanceof SupadataError) {
    console.error(e.error);            // e.g. 'invalid-request'
    console.error(e.message);          // human-readable message
    console.error(e.details);          // detailed description
    console.error(e.documentationUrl); // link to docs, may be ''
  } else {
    // Network-level or unexpected errors are plain Error/unknown types
    throw e;
  }
}
```

--------------------------------

### POST request to /v1/extract

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Example HTTP POST request to the Supadata API for extracting content from a URL.

```text
POST https://api.supadata.ai/v1/extract
x-api-key: <key>
Content-Type: application/json

{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","prompt":"Extract main topics"}
```

--------------------------------

### Example — missing jobId validation

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Example of missing jobId validation.

```typescript
try {
  await supadata.transcript.getJobStatus('');
} catch (e) {
  if (e instanceof SupadataError) {
    console.error(e.message); // "Missing jobId"
    console.error(e.error);   // "invalid-request"
  }
}
```

--------------------------------

### Get Playlist Details

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Retrieves playlist information. Requires id parameter.

```APIDOC
GET /youtube/playlist
```

--------------------------------

### crawl(request: CrawlRequest): Promise<JobId>

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Starts a crawl job for the given request and returns a job ID for tracking.

```APIDOC
## POST /web/crawl

### Description
Starts a crawl job for the given request and returns a job ID for tracking.

### Method
POST

### Endpoint
/web/crawl

### Parameters
#### Request Body
- **url** (string) - Required - The starting URL for the crawl
- **limit** (number) - Optional - Maximum number of pages to crawl
- **maxDepth** (number) - Optional - Maximum depth to crawl
- **includeSubdomains** (boolean) - Optional - Whether to include subdomains
- **ignoreSitemap** (boolean) - Optional - Whether to ignore the sitemap
- **excludePaths** (array) - Optional - Paths to exclude
- **includePaths** (array) - Optional - Paths to include
- **allowExternalLinks** (boolean) - Optional - Whether to allow external links
- **ignoreRobotsTxt** (boolean) - Optional - Whether to ignore robots.txt
- **outputFormat** (string) - Optional - Output format (e.g., 'markdown')

### Request Example
{
  "url": "https://supadata.ai",
  "limit": 10,
  "maxDepth": 2
}

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the crawl job

#### Response Example
{
  "jobId": "crawl_12345"
}
```

--------------------------------

### Get Video Details

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Retrieves metadata for a single YouTube video. Requires id parameter.

```APIDOC
GET /youtube/video
```

--------------------------------

### YouTube Transcript API

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Documentation for the YouTube transcript endpoint, including parameters, return types, and examples.

```APIDOC
## `transcript` — Get a YouTube video transcript

```typescript
/**
 * Handles YouTube Transcript operations.
 * @deprecated Use `supadata.transcript()` instead for multi-platform support
 */
transcript = Object.assign(
  async (params: TranscriptParams): Promise<Transcript> => {
    return this.fetch<Transcript>('/youtube/transcript', params);
  },
  {
    batch: async (
      params: YoutubeTranscriptBatchRequest
    ): Promise<YoutubeBatchJob> => {
      this.validateLimit(params, 1, 5000, 'batch operation');
      return this.fetch<YoutubeBatchJob>(
        '/youtube/transcript/batch',
        params,
        'POST'
      );
    },
  }
);
```

> **Deprecated.** Use `supadata.transcript()` (multi-platform) instead.

### `transcript(params)`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| params.videoId | string | exactly one of videoId/url | — | YouTube video ID (mutually exclusive with `url`) |
| params.url | string | exactly one of videoId/url | — | YouTube video URL (mutually exclusive with `videoId`) |
| params.lang | string | no | — | Language code for the transcript |
| params.text | boolean | no | — | Return only text content instead of timestamped chunks |

**Return:** `Promise<Transcript>` — transcript content, language, and available languages (see [types.md](../types.md)). HTTP: `GET /youtube/transcript`.

### `transcript.batch(params)`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| params.videoIds | string[] | source-dependent | — | Array of YouTube video IDs to fetch transcripts for (one of `videoIds`/`playlistId`/`channelId`) |
| params.playlistId | string | source-dependent | — | YouTube playlist ID to fetch transcripts for (one of `videoIds`/`playlistId`/`channelId`) |
| params.channelId | string | source-dependent | — | YouTube channel ID to fetch transcripts for (one of `videoIds`/`playlistId`/`channelId`) |
| params.lang | string | no | — | Language code for the transcript |
| params.text | boolean | no | — | Return only text content instead of timestamped chunks |

**Return:** `Promise<YoutubeBatchJob>` — `{ jobId: string }`. HTTP: `POST /youtube/transcript/batch`.

**Throws:** `SupadataError` `'invalid-request'` if `limit` is set and outside `[1, 5000]` (via `validateLimit` with `min=1, max=5000, operation='batch operation'`).

### Example

```typescript
const youTubeTranscript = await supadata.youtube.transcript({
  videoId: 'dQw4w9WgXcQ',
  lang: 'en',
  text: true,
});
console.log(youTubeTranscript.content);

const batchJob = await supadata.youtube.transcript.batch({
  videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'],
  lang: 'en',
});
console.log(`Batch job: ${batchJob.jobId}`);
```
```

--------------------------------

### GET /v1/metadata

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

Retrieves metadata for a media URL from YouTube, TikTok, Instagram, or Twitter.

```APIDOC
## [GET] /v1/metadata

### Description
Retrieves metadata for a media URL from YouTube, TikTok, Instagram, or Twitter.

### Method
GET

### Endpoint
/v1/metadata

### Parameters
#### Query Parameters
- **url** (string) - Required - Media URL from YouTube, TikTok, Instagram, or Twitter.

### Response
#### Success Response (200)
- **metadata** (object) - Media metadata.

#### Response Example
{
  "metadata": {}
}
```

--------------------------------

### Catching SupadataError

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata-error.md

Example of catching a SupadataError thrown by an SDK method.

```typescript
import { Supadata, SupadataError } from '@supadata/js';

const supadata = new Supadata({ apiKey: 'YOUR_API_KEY' });

try {
  await supadata.youtube.transcript({ videoId: 'INVALID_ID' });
} catch (e) {
  if (e instanceof SupadataError) {
    console.error(e.error);            // e.g. 'invalid-request'
    console.error(e.details);          // optional details
    console.error(e.documentationUrl); // link to docs, may be ''
  } else {
    // Network-level or unexpected errors are plain Error/unknown types
    throw e;
  }
}
```

--------------------------------

### TranscriptService Class

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Class declaration for TranscriptService with get and getJobStatus methods.

```typescript
export class TranscriptService extends BaseClient {
  get = async (params: GeneralTranscriptParams): Promise<TranscriptOrJobId> => {
    return this.fetch<TranscriptOrJobId>('/transcript', params);
  };

  getJobStatus = async (jobId: string): Promise<JobResult<Transcript>> => {
    if (!jobId) {
      throw new SupadataError({
        error: 'invalid-request',
        message: 'Missing jobId',
        details:
          'The jobId parameter is required to get transcript job status.',
      });
    }
    return this.fetch<JobResult<Transcript>>(`/transcript/${jobId}`);
  };
}
```

--------------------------------

### Get Transcript

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Retrieves the transcript for a YouTube video. Requires exactly one of videoId or url. Optional lang and text parameters.

```APIDOC
GET /youtube/transcript
```

--------------------------------

### Get Channel Details

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Retrieves channel information. Requires id parameter which can be a URL, channel ID, or handle.

```APIDOC
GET /youtube/channel
```

--------------------------------

### Get Channel Videos

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Retrieves video IDs for a channel. Requires id. Optional limit (1-5000) and type (video, short, live, all). Returns VideoIds object.

```APIDOC
GET /youtube/channel/videos
```

--------------------------------

### GET /v1/transcript

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

Retrieves a transcript for a given media URL or video ID. Supports timestamped chunks or plain text output, language selection, and asynchronous job processing.

```APIDOC
## [GET] /v1/transcript

### Description
Retrieves the transcript for a given media URL or video ID. Supports timestamped chunks or plain text output, language selection, and asynchronous job processing.

### Method
GET

### Endpoint
/v1/transcript

### Parameters
#### Query Parameters
- **url** (string) - Required - Media URL from YouTube, TikTok, Instagram, or Twitter.
- **lang** (string) - Optional - Language code for the transcript.
- **text** (boolean) - Optional - When true, returns plain text instead of timestamped chunks.
- **chunkSize** (number) - Optional - Size of transcript chunks.
- **mode** (string) - Optional - Mode of transcript generation: 'native', 'auto', or 'generate'.

### Response
#### Success Response (200)
- **content** (TranscriptChunk[] | string) - Timestamped chunks or plain text.
- **lang** (string) - Transcript language.
- **availableLangs** (string[]) - All available languages.

#### Response Example
{
  "content": [
    {
      "text": "Hello world",
      "offset": 0,
      "duration": 1000,
      "lang": "en"
    }
  ],
  "lang": "en",
  "availableLangs": ["en", "es"]
}
```

--------------------------------

### fetchUrl method signature

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/base-client.md

The protected method signature for fetchUrl, which performs HTTP requests with a default GET method and optional body.

```typescript
protected async fetchUrl<T>(
  url: string,
  method: 'GET' | 'POST' = 'GET',
  body?: Record<string, any>
): Promise<T>
```

--------------------------------

### Initialization

Source: https://github.com/supadata-ai/js/blob/main/README.md

Import the SDK and initialize the Supadata client with your API key.

```typescript
import {
  Crawl,
  CrawlJob,
  ExtractJobResult,
  JobId,
  JobResult,
  Map,
  Metadata,
  Scrape,
  Supadata,
  Transcript,
  TranscriptOrJobId,
  YoutubeChannel,
  YoutubePlaylist,
  YoutubeVideo,
} from '@supadata/js';

// Initialize the client
const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});
```

--------------------------------

### new Supadata(config)

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata.md

Instantiates the Supadata client with the provided configuration. The constructor requires an apiKey and optionally accepts a baseUrl to override the default endpoint.

```APIDOC
## new Supadata(config)

### Description
Creates a new Supadata client instance. The constructor initializes all internal services (YouTube, Web, Transcript, Extract) with the provided configuration.

### Method
Constructor

### Endpoint
N/A (SDK constructor)

### Parameters
#### Constructor Parameters
- **config** (SupadataConfig) - Required - Configuration object. `apiKey` is required; `baseUrl` is optional (defaults to `https://api.supadata.ai/v1`).

### Request Example
```typescript
import { Supadata } from '@supadata/js';

const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY', // required — get one at https://supadata.ai
  baseUrl: 'https://api.supadata.ai/v1', // optional — overrides the default endpoint
});
```

### Response
#### Success Response
Returns a configured Supadata instance with public properties `youtube` and `web`, and callable properties `transcript` and `extract`.

#### Response Example
```typescript
const supadata = new Supadata({ apiKey: 'YOUR_API_KEY' });
// supadata.youtube, supadata.web, supadata.transcript, supadata.extract are available
```
```

--------------------------------

### Metadata

Source: https://github.com/supadata-ai/js/blob/main/README.md

Retrieve media metadata from a supported platform URL.

```typescript
// Get media metadata from any supported platform (YouTube, TikTok, Instagram, Twitter)
const metadata = await supadata.metadata({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
});

// The metadata object contains comprehensive information about the media
console.log(metadata);
```

--------------------------------

### Import YouTubeService

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Import the YouTubeService class from the @supadata/js package. This is the entry point for using YouTube-specific operations.

```typescript
import { YouTubeService } from '@supadata/js';
```

--------------------------------

### Import BaseClient

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/base-client.md

Import statement for the BaseClient class from the package root.

```typescript
import { BaseClient } from '@supadata/js';
```

--------------------------------

### Import WebService

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Import the WebService class from the @supadata/js package.

```typescript
import { WebService } from '@supadata/js';
```

--------------------------------

### map(url: string): Promise<SiteMap>

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Maps a site's links by crawling the given URL and returning a sitemap structure.

```APIDOC
## GET /web/map

### Description
Maps a site's links by crawling the given URL and returning a sitemap structure.

### Method
GET

### Endpoint
/web/map

### Parameters
#### Query Parameters
- **url** (string) - Required - URL of the site to map

### Request Example
GET /web/map?url=https://supadata.ai

### Response
#### Success Response (200)
- **url** (string) - The URL of the mapped site
- **links** (array) - List of links found on the site

#### Response Example
{
  "url": "https://supadata.ai",
  "links": ["https://supadata.ai/docs", "https://supadata.ai/pricing"]
}
```

--------------------------------

### GET /v1/youtube/transcript/translate

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

Translates a YouTube video transcript into a specified language.

```APIDOC
## [GET] /v1/youtube/transcript/translate

### Description
Translates a YouTube video transcript into a specified language.

### Method
GET

### Endpoint
/v1/youtube/transcript/translate

### Parameters
#### Query Parameters
- **videoId** (string) - Required (exactly one of videoId/url) - YouTube video ID.
- **url** (string) - Required (exactly one of videoId/url) - YouTube video URL.
- **lang** (string) - Required - Target language code for translation.
- **text** (boolean) - Optional - When true, returns plain text instead of timestamped chunks.

### Response
#### Success Response (200)
- **content** (TranscriptChunk[] | string) - Translated timestamped chunks or plain text.
- **lang** (string) - Translated language.

#### Response Example
{
  "content": [
    {
      "text": "Hola mundo",
      "offset": 0,
      "duration": 1000,
      "lang": "es"
    }
  ],
  "lang": "es"
}
```

--------------------------------

### Constructor Signature

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/base-client.md

Constructor signature for BaseClient.

```typescript
constructor(config: SupadataConfig)
```

--------------------------------

### ExtractService Class

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Class declaration for ExtractService with methods get and getResults.

```typescript
export class ExtractService extends BaseClient {
  get = async (params: ExtractParams): Promise<JobId> => {
    return this.fetch<JobId>('/extract', params, 'POST');
  };

  getResults = async (jobId: string): Promise<ExtractJobResult> => {
    return this.fetch<ExtractJobResult>(`/extract/${jobId}`);
  };
}
```

--------------------------------

### Request construction

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/base-client.md

The exact source code for constructing the fetch request options, including headers and optional POST body.

```typescript
const options: RequestInit = {
  method,
  headers: {
    'x-api-key': this.config.apiKey,
    'Content-Type': 'application/json',
    'User-Agent': USER_AGENT,
  },
};

if (method === 'POST' && body) {
  options.body = JSON.stringify(body);
}
```

--------------------------------

### GET /v1/transcript/{jobId}

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

Retrieves the status and result of an asynchronous transcript job.

```APIDOC
## [GET] /v1/transcript/{jobId}

### Description
Retrieves the status and result of an asynchronous transcript job.

### Method
GET

### Endpoint
/v1/transcript/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The job ID returned when the transcript request was submitted asynchronously.

### Response
#### Success Response (200)
- **content** (TranscriptChunk[] | string) - Timestamped chunks or plain text.
- **lang** (string) - Transcript language.
- **availableLangs** (string[]) - All available languages.

#### Response Example
{
  "content": [
    {
      "text": "Hello world",
      "offset": 0,
      "duration": 1000,
      "lang": "en"
    }
  ],
  "lang": "en",
  "availableLangs": ["en", "es"]
}
```

--------------------------------

### Import ExtractService

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/extract-service.md

Import the ExtractService class from the package root.

```typescript
import { ExtractService } from '@supadata/js';
```

--------------------------------

### Type Definitions

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

All type definitions from the reference documentation.

```typescript
export interface SupadataConfig {
  apiKey: string;
  baseUrl?: string;
}
```

```typescript
export interface MetadataParams {
  url: string;
}
```

```typescript
export interface TranscriptChunk {
  text: string;
  offset: number;
}
```

```typescript
export interface Transcript {
  content: TranscriptChunk[] | string;
  lang: string;
  availableLangs: string[];
}
```

```typescript
export interface TranslatedTranscript {
  content: TranscriptChunk[] | string;
  lang: string;
}
```

```typescript
export interface GeneralTranscriptParams {
  url: string;
  lang?: string;
  text?: boolean;
  chunkSize?: number;
  mode?: 'native' | 'auto' | 'generate';
}
```

```typescript
export type TranscriptParams = {
  lang?: string;
  text?: boolean;
} & ExactlyOne<{ videoId: string; url: string }, 'videoId' | 'url'>;
```

```typescript
export interface TranslateParams extends Omit<TranscriptParams, 'lang'> {
  lang: string;
}
```

```typescript
export type TranscriptOrJobId = Transcript | JobId;
```

--------------------------------

### Create Transcript Batch Job

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Creates a batch job to fetch transcripts for multiple videos, a playlist, or a channel. Body must contain videoIds, playlistId, or channelId. Optional lang, text, and limit (1-5000). Returns a YoutubeBatchJob with jobId.

```APIDOC
POST /youtube/transcript/batch
```

--------------------------------

### Extract

Source: https://github.com/supadata-ai/js/blob/main/README.md

Extract structured data from videos using AI, either with a prompt or a JSON schema, and poll for results.

```typescript
// Extract structured data from video content using AI
// With a prompt (AI determines the schema)
const job = await supadata.extract({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  prompt: 'Extract the main topics and key takeaways',
});
console.log(`Started extract job: ${job.jobId}`);

// With a JSON Schema (for structured output)
const jobWithSchema = await supadata.extract({
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  schema: {
    topics: { type: 'array', items: { type: 'string' } },
    summary: { type: 'string' },
  },
  required: ['topics', 'summary'],
});

// Poll for results
const result = await supadata.extract.getResults(job.jobId);
if (result.status === 'completed') {
  console.log('Extracted data:', result.data);
  // If no schema was provided, the AI-generated schema is available:
  console.log('Generated schema:', result.schema);
} else if (result.status === 'failed') {
  console.error('Extract failed:', result.error);
} else {
  console.log('Job status:', result.status); // 'queued' or 'active'
}
```

--------------------------------

### Import TranscriptService

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/transcript-service.md

Import statement for TranscriptService and GeneralTranscriptParams.

```typescript
import { TranscriptService, GeneralTranscriptParams } from '@supadata/js';
```

--------------------------------

### Web Operations

Source: https://github.com/supadata-ai/js/blob/main/README.md

This code demonstrates web scraping, site mapping, crawling, and retrieving crawl results using the Supadata client.

```typescript
// Scrape web content
const webContent: Scrape = await supadata.web.scrape('https://supadata.ai');

// Map website URLs
const siteMap: Map = await supadata.web.map('https://supadata.ai');

// Crawl website
const crawl: JobId = await supadata.web.crawl({
  url: 'https://supadata.ai',
  limit: 10,
});

// Get crawl job results
const crawlResults: CrawlJob = await supadata.web.getCrawlResults(crawl.jobId);
```

--------------------------------

### Playlist resource definition

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Defines the playlist resource with a main function to fetch playlist info and a nested videos function to fetch video IDs.

```typescript
playlist = Object.assign(
  async (params: ResourceParams): Promise<YoutubePlaylist> => {
    return this.fetch<YoutubePlaylist>('/youtube/playlist', params);
  },
  {
    videos: async (params: PlaylistVideosParams): Promise<VideoIds> => {
      this.validateLimit(params);
      return this.fetch<VideoIds>('/youtube/playlist/videos', params);
    },
  }
);
```

--------------------------------

### scrape(url: string): Promise<Scrape>

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Scrapes a single webpage and returns its content in Markdown format along with metadata.

```APIDOC
## GET /web/scrape

### Description
Scrapes a single webpage and returns its content in Markdown format along with metadata.

### Method
GET

### Endpoint
/web/scrape

### Parameters
#### Query Parameters
- **url** (string) - Required - URL of the webpage to scrape

### Request Example
GET /web/scrape?url=https://supadata.ai

### Response
#### Success Response (200)
- **url** (string) - The URL of the scraped page
- **content** (string) - The page content in Markdown
- **name** (string) - The page name/title
- **description** (string) - The page description
- **ogUrl** (string) - The Open Graph URL
- **countCharacters** (number) - The character count of the content
- **urls** (array) - List of URLs found on the page

#### Response Example
{
  "url": "https://supadata.ai",
  "content": "# Supadata\n...",
  "name": "Supadata",
  "description": "...",
  "ogUrl": "https://supadata.ai",
  "countCharacters": 1234,
  "urls": ["https://supadata.ai/docs"]
}
```

--------------------------------

### Job and Batch Types

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

TypeScript interfaces and types for job management and YouTube batch operations.

```typescript
export interface JobId {
  jobId: string;
}
```

```typescript
export type JobStatus = 'queued' | 'active' | 'completed' | 'failed';
```

```typescript
export interface JobResult<T = any> {
  status: JobStatus;
  result?: T | null;
  error?: {
    error: SupadataError['error'];
    message: string;
    details: string;
    documentationUrl?: string;
  } | null;
}
```

```typescript
export interface YoutubeBatchJob extends JobId {}
```

```typescript
export type YoutubeBatchJobStatus = JobStatus;
```

```typescript
export interface YoutubeBatchResultItem {
  videoId: string;
  transcript?: Transcript;
  video?: YoutubeVideo;
  errorCode?: string;
}
```

```typescript
export interface YoutubeBatchStats {
  total: number;
  succeeded: number;
  failed: number;
}
```

```typescript
export interface YoutubeBatchResults {
  status: YoutubeBatchJobStatus;
  results?: YoutubeBatchResultItem[];
  stats?: YoutubeBatchStats;
  completedAt?: string;
}
```

```typescript
export interface YoutubeBatchSource {
  videoIds?: string[];
  playlistId?: string;
  channelId?: string;
  limit?: number;
}

export interface YoutubeTranscriptBatchRequest extends YoutubeBatchSource {
  lang?: string;
  text?: boolean;
}

export interface YoutubeVideoBatchRequest extends YoutubeBatchSource {}
```

--------------------------------

### Get Batch Job Results

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/endpoints.md

Retrieves the results of a batch job using its jobId. Returns YoutubeBatchResults with status, results, stats, and completedAt.

```APIDOC
GET /youtube/batch/{jobId}
```

--------------------------------

### Map a webpage to extract all links

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/web-service.md

Calls supadata.web.map with a URL and logs the number of links found. The method returns a Promise<SiteMap> containing an array of URLs.

```typescript
const siteMap = await supadata.web.map('https://supadata.ai');
console.log(`Found ${siteMap.urls.length} links`);
```

--------------------------------

### SiteMap Interface

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

Represents a sitemap containing a list of URLs.

```typescript
export interface SiteMap {
  urls: string[];
}
```

--------------------------------

### Error Handling on Invalid Limit

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/youtube-service.md

Example of error handling when an invalid limit is passed to the batch method, catching SupadataError and logging message and details.

```typescript
try {
  await supadata.youtube.video.batch({ videoIds: ['dQw4w9WgXcQ'], limit: 99999 });
} catch (e) {
  if (e instanceof SupadataError) {
    console.error(e.message); // "Invalid limit for batch operation."
    console.error(e.details); // "The limit must be between 1 and 5000."
  }
}
```

--------------------------------

### Resource and Video Parameters

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/types.md

Defines parameter interfaces for resource-based operations: base ResourceParams, ChannelVideosParams with optional limit and type, PlaylistVideosParams with optional limit, and VideoIds for storing multiple video IDs.

```typescript
export interface ResourceParams {
  id: string;
}

export interface ChannelVideosParams extends ResourceParams {
  limit?: number;
  type?: 'video' | 'short' | 'live' | 'all';
}

export interface PlaylistVideosParams extends ResourceParams {
  limit?: number;
}

export interface VideoIds {
  videoIds: string[];
  shortIds: string[];
  liveIds: string[];
}
```

--------------------------------

### BaseClient Class Declaration

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/base-client.md

Class declaration of BaseClient with protected config, constructor, and fetch methods.

```typescript
export class BaseClient {
  protected config: SupadataConfig;

  constructor(config: SupadataConfig) {
    this.config = config;
  }

  protected async fetch<T>(
    endpoint: string,
    params: Record<string, any> = {},
    method: 'GET' | 'POST' = 'GET'
  ): Promise<T> { ... }

  protected async fetchUrl<T>(
    url: string,
    method: 'GET' | 'POST'
  ): Promise<T> { ... }
}
```

--------------------------------

### Import Supadata from @supadata/js

Source: https://github.com/supadata-ai/js/blob/main/_autodocs/api-reference/supadata.md

Import the Supadata class from the @supadata/js package.

```typescript
import { Supadata } from '@supadata/js';
```
Tokens:
Raw