supadata-llms-full.txt · Property Ontology

plaintext4035 lines140 KB

1	# Get Account Information
2	Source: https://docs.supadata.ai/api-reference/endpoint/account/me
3
4	v1-openapi GET /me
5	Retrieve organization details, plan information, and credit usage.
6
7
8
9	# Extract
10	Source: https://docs.supadata.ai/api-reference/endpoint/extract/extract
11
12	v1-openapi POST /extract
13	Use AI to analyze video content and extract structured data. Provide either a prompt describing what to extract, a JSON Schema for the output format, or both. Supports YouTube, TikTok, Instagram, Twitter/X, and Facebook videos. Returns a job ID for asynchronous processing. Use the `/extract/:jobId` endpoint to poll for results.
14
15
16
17	# Extract Result
18	Source: https://docs.supadata.ai/api-reference/endpoint/extract/extract-get
19
20	v1-openapi GET /extract/{jobId}
21	Get results for an extract job by job ID.
22
23
24
25	# Metadata
26	Source: https://docs.supadata.ai/api-reference/endpoint/metadata/metadata
27
28	v1-openapi GET /metadata
29	Fetch metadata from any supported internet media including YouTube, TikTok, Instagram, Twitter/X and Facebook posts. Returns unified metadata with a predictable structure across all platforms.
30
31
32
33	# Transcript
34	Source: https://docs.supadata.ai/api-reference/endpoint/transcript/transcript
35
36	v1-openapi GET /transcript
37	Get transcript from a supported video platform (YouTube, TikTok, Twitter, Instagram, Facebook) or file URL. If the video is too large to return transcript immediately, request returns a job ID. Use the `/transcript/:jobId` endpoint to get job results.
38
39
40
41	# Transcript Result
42	Source: https://docs.supadata.ai/api-reference/endpoint/transcript/transcript-get
43
44	v1-openapi GET /transcript/{jobId}
45	Get results for a transcript job by job ID.
46
47
48
49	# Crawl
50	Source: https://docs.supadata.ai/api-reference/endpoint/web/crawl
51
52	v1-openapi POST /web/crawl
53	Create a crawl job to extract content from all pages on a website.
54
55
56
57	# Crawl Status
58	Source: https://docs.supadata.ai/api-reference/endpoint/web/crawl-get
59
60	v1-openapi GET /web/crawl/{jobId}
61	Get the status and results of a crawl by job ID.
62
63
64
65	# Map
66	Source: https://docs.supadata.ai/api-reference/endpoint/web/map
67
68	v1-openapi GET /web/map
69	Extract all links found on a whole website.
70
71
72
73	# Scrape
74	Source: https://docs.supadata.ai/api-reference/endpoint/web/scrape
75
76	v1-openapi GET /web/scrape
77	Extract content from any web page to Markdown format.
78
79
80
81	# Batch Result
82	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/batch-get
83
84	v1-openapi GET /youtube/batch/{jobId}
85	Get the status and results of a YouTube batch job.
86
87
88
89	# Channel
90	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel
91
92	v1-openapi GET /youtube/channel
93	Get metadata for a YouTube channel.
94
95
96
97	# Channel Videos
98	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel-videos
99
100	v1-openapi GET /youtube/channel/videos
101	Get video IDs from a YouTube channel.
102
103
104
105	# Playlist
106	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/playlist
107
108	v1-openapi GET /youtube/playlist
109	Get metadata for a YouTube playlist.
110
111
112
113	# Playlist Videos
114	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/playlist-videos
115
116	v1-openapi GET /youtube/playlist/videos
117	Get video IDs from a YouTube playlist.
118
119
120
121	# Search
122	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/search
123
124	v1-openapi GET /youtube/search
125	Search YouTube for videos, channels, and playlists with advanced filters.
126
127
128
129	# Transcript
130	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/transcript
131
132	v1-openapi GET /youtube/transcript
133	Get transcript from YouTube video in various formats and languages. If the `lang` parameter is not provided or the transcript is not available in the requested language, the API defaults to the first available language.
134
135
136
137	# Transcript Batch
138	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/transcript-batch
139
140	v1-openapi POST /youtube/transcript/batch
141	Create a batch job to get transcripts of multiple YouTube videos
142
143
144
145	# Translate Transcript
146	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/translation
147
148	v1-openapi GET /youtube/transcript/translate
149	Translate YouTube video transcript into different languages.
150
151
152
153	# Video Batch
154	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch
155
156	v1-openapi POST /youtube/video/batch
157	Create a batch job to fetch metadata of multiple YouTube videos
158
159
160
161	# Video
162	Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get
163
164	v1-openapi GET /youtube/video
165	Get metadata for a YouTube video.
166
167
168
169	# Supadata API Reference \| Web Scraping & YouTube Transcripts
170	Source: https://docs.supadata.ai/api-reference/introduction
171
172	Complete API reference for Supadata. Extract web content, YouTube transcripts, video metadata, and more. Includes authentication, rate limits, and endpoint documentation.
173
174	## Features
175
176	<CardGroup>
177	<Card title="Transcript" icon="book" href="/api-reference/endpoint/transcript/transcript">
178	Get social media or file transcript.
179	</Card>
180
181	<Card title="Metadata" icon="file" href="/api-reference/endpoint/metadata/metadata">
182	Get social media post metadata.
183	</Card>
184
185	<Card title="Extract" icon="wand-magic-sparkles" href="/api-reference/endpoint/extract/extract">
186	Extract structured data from videos using AI.
187	</Card>
188
189	<Card title="Web" icon="markdown" href="/api-reference/endpoint/web/scrape">
190	Extract content from any website in markdown format.
191	</Card>
192	</CardGroup>
193
194	## Base URL
195
196	All requests contain the following base URL:
197
198	```sh theme={null}
199	https://api.supadata.ai/v1
200	```
201
202	## Authentication
203
204	For authentication, it's required to include a `x-api-key` header.
205
206	```sh theme={null}
207	x-api-key: {YOUR_API_KEY}
208	```
209
210	## Response codes
211
212	Supadata employs conventional HTTP status codes to signify the outcome of your requests.
213
214	Typically, 2xx HTTP status codes denote success, 4xx codes represent failures related to the user, and 5xx codes signal infrastructure problems.
215
216	\| Status \| Description \|
217	\| ------ \| -------------------------------------------- \|
218	\| 200 \| Request was successful. \|
219	\| 400 \| Verify the correctness of the parameters. \|
220	\| 401 \| The API key was not provided. \|
221	\| 402 \| Payment required. \|
222	\| 404 \| The requested resource could not be located. \|
223	\| 429 \| A plan limit has been surpassed. \|
224	\| 5xx \| Signifies a server error with Supadata. \|
225
226	Refer to the [Error Codes](/errors) section for a detailed explanation of all potential API errors.
227
228	## Rate limit
229
230	The Supadata API has a rate limit to ensure the stability and reliability of the service. The rate limit is applied to all endpoints and is based on the number of requests made within a specific time frame and your current subscription plan.
231
232	When you exceed the rate limit, you will receive a 429 response code.
233
234
235	# Community Resources
236	Source: https://docs.supadata.ai/community-resources
237
238	Explore tutorials, guides, and videos about using Supadata
239
240	## YouTube Videos
241
242	Browse our collection of community-created videos and tutorials organized by platform.
243
244	### Coding
245
246	<CodingVideos />
247
248	### n8n Integration
249
250	<N8nVideos />
251
252	### Make Integration
253
254	<MakeVideos />
255
256	### Zapier Integration
257
258	<ZapierVideos />
259
260	### Other Resources
261
262	<OtherVideos />
263
264
265	# Internal Error
266	Source: https://docs.supadata.ai/errors/internal-error
267
268	An internal server error occurred while processing your request. Explanation of the error and how to fix it.
269
270	An internal server error occurred while processing your request. This is a server-side error that indicates something went wrong on our end.
271
272	```json theme={null}
273	{
274	"error": "internal-error",
275	"message": "Internal Error",
276	"details": "An internal server error occurred",
277	"documentationUrl": "https://supadata.ai/documentation/errors/internal-error"
278	}
279	```
280
281	## Reasons and how to fix
282
283	This error occurs when there's an unexpected issue during request processing on our servers. Possible reasons include:
284
285	* Server-side processing error: an unexpected error occurred while processing the request.
286	* Database connection issues: temporary database connectivity or network problems.
287	* Service dependencies issues: one of our service dependencies is temporarily unavailable.
288
289	### To fix
290
291	1. Retry your request after a few moments
292	2. If the error persists, try with a different request payload
293	3. Check if the [Supadata status page](https://status.supadata.ai) indicates any ongoing issues
294
295	### Reach out to support
296
297	If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible.
298
299
300	# Invalid Request
301	Source: https://docs.supadata.ai/errors/invalid-request
302
303	It is an API error returned when the API fails to serve the request due to invalid request parameters.
304
305	It is an API error returned when the API fails to serve the request due to invalid request parameters.
306
307	```json theme={null}
308	{
309	"error": "invalid-request",
310	"message": "Invalid request",
311	"details": "Required parameters are missing from the request",
312	"documentationUrl": "https://supadata.ai/documentation/errors/invalid-request"
313	}
314	```
315
316	## Reasons and how to fix
317
318	### Invalid request parameters
319
320	The most common reason for the `invalid-request` error is that one or more of the request parameters are invalid or missing.
321
322	To fix this, ensure that all required parameters are included in the request and that they are correctly formatted and valid.
323
324	### Missing required parameters
325
326	If required parameters are missing from the request, this will trigger the `invalid-request` error.
327
328	To fix this, ensure that all mandatory parameters are provided in the request. Refer to the API documentation for a list of required parameters.
329
330	### Incorrect data types
331
332	Providing parameters with incorrect data types (e.g., a string instead of an integer) can lead to this error.
333
334	To fix this, verify that the data types of all parameters match the expected types as specified in the API documentation.
335
336	### Parameter value constraints
337
338	Some parameters may have constraints on their values (e.g., minimum or maximum length, specific formats). Violating these constraints will result in this error.
339
340	To fix this, check the constraints for each parameter in the API documentation and ensure that the provided values comply with these constraints.
341
342	### Syntax errors
343
344	Syntax errors in the request, such as missing commas or brackets in JSON, can make the request invalid.
345
346	To fix this, carefully review the syntax of your request and correct any errors. Using a JSON validator can help identify syntax issues.
347
348	### Reach out to support
349
350	If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible.
351
352
353	# Limit Exceeded
354	Source: https://docs.supadata.ai/errors/limit-exceeded
355
356	You have exceeded the allowed request rate or quota limits. Explanation of the error and how to fix it.
357
358	You have exceeded the allowed request rate or quota limits. This error occurs when you've reached the maximum number of requests allowed for your current plan or time period.
359
360	```json theme={null}
361	{
362	"error": "limit-exceeded",
363	"message": "Limit Exceeded",
364	"details": "You have exceeded the allowed request rate or quota limits",
365	"documentationUrl": "https://supadata.ai/documentation/errors/limit-exceeded"
366	}
367	```
368
369	## Reasons and how to fix
370
371	### Rate limit exceeded
372
373	You've made too many requests in a short time period.
374
375	To fix this, make sure to not call the API more often than the rate limit on your plan allows. Implement rate limiting in your application and consider batching multiple requests into a single call using our batch endpoints.
376
377	### Quota limit reached
378
379	You've reached your plan's monthly quota limit.
380
381	To fix this, check your [usage in the dashboard](https://dash.supadata.ai/organizations/settings/organization/billing) and consider upgrading your plan for higher limits, enable Auto Recharge, or wait for the next billing cycle.
382
383	### Reach out to support
384
385	If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible.
386
387
388	# Error Codes
389	Source: https://docs.supadata.ai/errors/list
390
391	A comprehensive list of all possible error codes you might encounter when using the Supadata API.
392
393	Below is a comprehensive list of all possible error codes you might encounter when using the Supadata API. Each error includes a description, HTTP status code, and a link to detailed documentation about how to handle it.
394
395	## Error Reference Table
396
397	\| Error Code \| Description \| HTTP Status \|
398	\| -------------------------------------------------------- \| ---------------------------------------------------------- \| ----------- \|
399	\| [Invalid Request](/errors/invalid-request) \| The request is invalid or malformed \| 400 \|
400	\| [Unauthorized](/errors/unauthorized) \| The request is unauthorized. Please check your API key \| 401 \|
401	\| [Upgrade Required](/errors/upgrade-required) \| This feature is not available on your current plan \| 402 \|
402	\| [Forbidden](/errors/forbidden) \| Access to this resource is forbidden \| 403 \|
403	\| [Not Found](/errors/not-found) \| The requested item could not be found \| 404 \|
404	\| [Limit Exceeded](/errors/limit-exceeded) \| You have exceeded the allowed request rate or quota limits \| 429 \|
405	\| [Transcript Unavailable](/errors/transcript-unavailable) \| No transcript is available for this video \| 206 \|
406	\| [Internal Error](/errors/internal-error) \| An internal server error occurred \| 500 \|
407
408	## Error Response Format
409
410	All errors follow a consistent JSON response format:
411
412	```json theme={null}
413	{
414	"error": "error-code",
415	"message": "Human readable error message",
416	"details": "Detailed explanation of the error",
417	"documentationUrl": "https://docs.supadata.ai/errors/error-code"
418	}
419	```
420
421
422	# Not Found
423	Source: https://docs.supadata.ai/errors/not-found
424
425	The requested resource could not be found. Explanation of the error and how to fix it.
426
427	The requested resource could not be found. This error occurs when you try to access a resource that doesn't exist or has been removed.
428
429	```json theme={null}
430	{
431	"error": "not-found",
432	"message": "Not Found",
433	"details": "The requested item could not be found",
434	"documentationUrl": "https://supadata.ai/documentation/errors/not-found"
435	}
436	```
437
438	## Reasons and how to fix
439
440	### Resource doesn't exist or was moved
441
442	The most common reason for this error is that the resource you're trying to access (eg. YouTube video) doesn't exist, was deleted, or was moved to a different location.
443
444	To fix this:
445
446	1. Double-check the resource identifier (ID, URL, etc.)
447	2. Verify that the resource hasn't been deleted or moved to a different location
448	3. Ensure you're using the correct API endpoint
449
450	### Incorrect API endpoint
451
452	The error might occur if you're using an incorrect path to access the Supadata API
453
454	To fix this, review the API documentation for the correct endpoint structure and make sure you're using the correct path.
455
456	### Reach out to support
457
458	If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible.
459
460
461	# Transcript Unavailable
462	Source: https://docs.supadata.ai/errors/transcript-unavailable
463
464	No transcript is available for this video. Explanation of the error and how to fix it.
465
466	No transcript is available for this video. This error occurs when you try to access a transcript for a YouTube, TikTok, Instagram or X (Twitter) video that doesn't have one available.
467
468	```json theme={null}
469	{
470	"error": "transcript-unavailable",
471	"message": "Transcript Unavailable",
472	"details": "No transcript is available for this video",
473	"documentationUrl": "https://supadata.ai/documentation/errors/transcript-unavailable"
474	}
475	```
476
477	## Reasons and how to fix
478
479	### Video has no captions
480
481	The YouTube, TikTok, Instagram or X (Twitter) video doesn't have any captions or subtitles available.
482
483	To fix this:
484
485	1. Use the [`/transcript`](/get-transcript) endpoint with `mode=generate` or `mode=auto` option to generate captions for the video
486	2. Consider using a different video that has captions
487
488	### Reach out to support
489
490	If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible.
491
492
493	# Unauthorized
494	Source: https://docs.supadata.ai/errors/unauthorized
495
496	The request is unauthorized. Explanation of the error and how to fix it.
497
498	The request is unauthorized. This error occurs when your Supadata API key is not provided, is invalid or expired.
499
500	```json theme={null}
501	{
502	"error": "unauthorized",
503	"message": "Unauthorized",
504	"details": "The request is unauthorized. Please check your API key.",
505	"documentationUrl": "https://supadata.ai/documentation/errors/unauthorized"
506	}
507	```
508
509	## Reasons and how to fix
510
511	### Supadata API key not provided
512
513	The error might occur if you haven't included the Supadata API key in your request.
514
515	To fix this:
516
517	1. Ensure you're including the Supadata API key in the request headers
518	2. Verify the header name is correct (`x-api-key: YOUR_API_KEY` where `YOUR_API_KEY` is your API key from the dashboard)
519	3. Check if your API client is properly configured to send the key
520
521	### Invalid API key
522
523	The most common reason for this error is that the API key you're using is invalid.
524
525	To fix this:
526
527	1. Verify that you're using the correct API key
528	2. Ensure there are no extra spaces or special characters in the key
529
530	### Expired API key
531
532	Your API key might have expired.
533
534	To fix this:
535
536	1. Check your API key's expiration date in the [Supadata dashboard](https://dash.supadata.ai)
537	2. Generate a new API key if necessary
538	3. Update your application with the new key
539
540	### Reach out to support
541
542	If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible.
543
544
545	# Upgrade Required
546	Source: https://docs.supadata.ai/errors/upgrade-required
547
548	This feature is not available on your current plan. Explanation of the error and how to fix it.
549
550	This feature is not available on your current plan. This error occurs when you try to access a feature or endpoint that requires a higher tier subscription.
551
552	```json theme={null}
553	{
554	"error": "upgrade-required",
555	"message": "Upgrade Required",
556	"details": "This feature is not available on your current plan. Upgrade your plan to access it.",
557	"documentationUrl": "https://supadata.ai/documentation/errors/upgrade-required"
558	}
559	```
560
561	## Reasons and how to fix
562
563	### Feature not available in current plan
564
565	The feature you're trying to use is only available in higher-tier plans.
566
567	To fix this:
568
569	1. Review the feature availability in our pricing page
570	2. Compare your current plan with available upgrades
571	3. Consider upgrading to a plan that includes the feature
572
573	### Reach out to support
574
575	If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible.
576
577
578	# Extract
579	Source: https://docs.supadata.ai/get-extract
580
581	Use this API endpoint to extract structured data from videos hosted on YouTube, TikTok, Instagram, X (Twitter), Facebook or a public file URL. Supadata uses AI to analyze the video and return data matching your prompt or schema.
582
583	This endpoint powers Supadata's [AI video analysis API](https://supadata.ai/video-analysis-api) — use AI to turn any supported video into structured JSON matching your own prompt or schema.
584
585	<Frame>
586	<img />
587	</Frame>
588
589	## Quick Start
590
591	### Request
592
593	<CodeGroup>
594	```javascript Node.js theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
595	import { Supadata } from '@supadata/js';
596
597	const supadata = new Supadata({
598	apiKey: 'YOUR_API_KEY',
599	});
600
601	// Start extract job
602	const job = await supadata.extract({
603	url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
604	prompt: 'How many times does a dog appear in this video? Describe each appearance.',
605	});
606
607	console.log(job.jobId);
608	```
609
610	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
611	from supadata import Supadata
612
613	supadata = Supadata(api_key="YOUR_API_KEY")
614
615	# Start extract job
616	job = supadata.extract(
617	url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
618	prompt="How many times does a dog appear in this video? Describe each appearance."
619	)
620
621	print(job.job_id)
622	```
623
624	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
625	curl -X POST "https://api.supadata.ai/v1/extract" \
626	-H "x-api-key: YOUR_API_KEY" \
627	-H "Content-Type: application/json" \
628	-d '{
629	"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
630	"prompt": "How many times does a dog appear in this video? Describe each appearance."
631	}'
632	```
633	</CodeGroup>
634
635	### Response (HTTP 202)
636
637	```json theme={null}
638	{
639	"jobId": "123e4567-e89b-12d3-a456-426614174000"
640	}
641	```
642
643	The extract endpoint always returns a job ID for asynchronous processing. Use the job ID to [poll for results](#getting-job-results).
644
645	### Job Result
646
647	```json theme={null}
648	{
649	"status": "completed",
650	"data": {
651	"totalAppearances": 3,
652	"appearances": [
653	{ "timestamp": "0:12", "description": "Golden retriever runs across the park" },
654	{ "timestamp": "1:45", "description": "Same dog catches a frisbee mid-air" },
655	{ "timestamp": "3:20", "description": "Dog rolls over on the grass for belly rubs" }
656	]
657	},
658	"schema": {
659	"type": "object",
660	"properties": {
661	"totalAppearances": {
662	"type": "number"
663	},
664	"appearances": {
665	"type": "array",
666	"items": {
667	"type": "object",
668	"properties": {
669	"timestamp": { "type": "string" },
670	"description": { "type": "string" }
671	},
672	"required": ["timestamp", "description"]
673	}
674	}
675	},
676	"required": ["totalAppearances", "appearances"]
677	}
678	}
679	```
680
681	## Specification
682
683	### Endpoint
684
685	`POST https://api.supadata.ai/v1/extract`
686
687	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
688
689	### Request Body
690
691	\| Parameter \| Type \| Required \| Description \|
692	\| --------- \| ------ \| -------- \| ----------------------------------------------------------------------------------------------------------------------------- \|
693	\| url \| string \| Yes \| URL of the video to extract data from. Must be either YouTube, TikTok, Instagram, X (Twitter), Facebook or a public file URL. \|
694	\| prompt \| string \| No \| Description of what data to extract from the video. Required if `schema` is not provided. \|
695	\| schema \| object \| No \| JSON Schema defining the structure of data to extract. Required if `prompt` is not provided. \|
696
697	<Info>
698	At least one of `prompt` or `schema` must be provided. You can also provide both for maximum control over the output.
699	</Info>
700
701	<Note>
702	The `/extract` endpoint uses AI to analyze video content (what is seen and heard in the video). It does not retrieve transcripts, titles, descriptions, or platform metrics. For those, use the dedicated [Transcript](/get-transcript) or [Metadata](/get-metadata) endpoints.
703	</Note>
704
705	### Schema
706
707	The `schema` parameter accepts a [JSON Schema](https://json-schema.org/) object that defines the expected structure of the extracted data. This is useful for building pipelines that need consistent, predictable output formats.
708
709	#### How it works
710
711	* Prompt only: When only `prompt` is provided, the AI automatically generates a JSON Schema based on the prompt. The generated schema is returned in the `schema` field of the response, so you can reuse it for future requests to get consistent outputs.
712
713	<Info>
714	With prompt-only mode, the response structure (key names, nesting, and types) may vary between calls since the AI generates the schema dynamically. To ensure a consistent output format across requests, provide an explicit `schema`.
715	</Info>
716
717	* Schema only: When only `schema` is provided, the AI extracts data structured exactly according to the schema.
718
719	* Both prompt and schema: The schema defines the output structure, while the prompt guides what content to extract. This gives you maximum control over the extraction.
720
721	#### Example with schema
722
723	```json theme={null}
724	{
725	"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
726	"schema": {
727	"type": "object",
728	"properties": {
729	"totalAppearances": {
730	"type": "number",
731	"description": "Total number of times a dog appears"
732	},
733	"appearances": {
734	"type": "array",
735	"items": {
736	"type": "object",
737	"properties": {
738	"timestamp": { "type": "string", "description": "Timestamp of the appearance" },
739	"description": { "type": "string", "description": "What the dog is doing" }
740	},
741	"required": ["timestamp", "description"]
742	},
743	"description": "Each individual dog appearance"
744	}
745	},
746	"required": ["totalAppearances", "appearances"]
747	}
748	}
749	```
750
751	<Tip>
752	Start with just a `prompt` to let the AI generate a schema, then reuse the returned `schema` in subsequent requests for consistent outputs across multiple videos.
753	</Tip>
754
755	#### Schema Examples
756
757	Copy any of these schemas and use them directly in your requests.
758
759	<AccordionGroup>
760	<Accordion title="Recipe Extraction" icon="utensils">
761	Extract cooking recipes with ingredients, steps and nutritional info.
762
763	```json theme={null}
764	{
765	"type": "object",
766	"properties": {
767	"title": {
768	"type": "string",
769	"description": "Name of the dish"
770	},
771	"servings": {
772	"type": "number",
773	"description": "Number of servings"
774	},
775	"prepTimeMinutes": {
776	"type": "number",
777	"description": "Preparation time in minutes"
778	},
779	"cookTimeMinutes": {
780	"type": "number",
781	"description": "Cooking time in minutes"
782	},
783	"ingredients": {
784	"type": "array",
785	"items": {
786	"type": "object",
787	"properties": {
788	"name": { "type": "string" },
789	"quantity": { "type": "string" }
790	},
791	"required": ["name", "quantity"]
792	},
793	"description": "List of ingredients with quantities"
794	},
795	"steps": {
796	"type": "array",
797	"items": { "type": "string" },
798	"description": "Step-by-step cooking instructions"
799	}
800	},
801	"required": ["title", "ingredients", "steps"]
802	}
803	```
804	</Accordion>
805
806	<Accordion title="Video Chapters" icon="list-ol">
807	Extract timestamped chapters and sections from a video.
808
809	```json theme={null}
810	{
811	"type": "object",
812	"properties": {
813	"title": {
814	"type": "string",
815	"description": "Video title"
816	},
817	"chapters": {
818	"type": "array",
819	"items": {
820	"type": "object",
821	"properties": {
822	"title": {
823	"type": "string",
824	"description": "Chapter title"
825	},
826	"startTime": {
827	"type": "string",
828	"description": "Start timestamp (e.g. 0:00, 2:35, 1:02:15)"
829	},
830	"summary": {
831	"type": "string",
832	"description": "Brief summary of what is covered"
833	}
834	},
835	"required": ["title", "startTime", "summary"]
836	},
837	"description": "Ordered list of video chapters"
838	}
839	},
840	"required": ["title", "chapters"]
841	}
842	```
843	</Accordion>
844
845	<Accordion title="Key Takeaways" icon="lightbulb">
846	Extract main points, takeaways and action items from educational or business content.
847
848	```json theme={null}
849	{
850	"type": "object",
851	"properties": {
852	"topic": {
853	"type": "string",
854	"description": "Main topic of the video"
855	},
856	"summary": {
857	"type": "string",
858	"description": "One-paragraph summary"
859	},
860	"keyTakeaways": {
861	"type": "array",
862	"items": { "type": "string" },
863	"description": "Main points and insights"
864	},
865	"actionItems": {
866	"type": "array",
867	"items": { "type": "string" },
868	"description": "Concrete action items or next steps"
869	}
870	},
871	"required": ["topic", "summary", "keyTakeaways"]
872	}
873	```
874	</Accordion>
875
876	<Accordion title="Fitness Routine" icon="dumbbell">
877	Extract workout routines with exercises, sets, reps and rest periods.
878
879	```json theme={null}
880	{
881	"type": "object",
882	"properties": {
883	"routineName": {
884	"type": "string",
885	"description": "Name of the workout routine"
886	},
887	"difficulty": {
888	"type": "string",
889	"enum": ["beginner", "intermediate", "advanced"],
890	"description": "Difficulty level"
891	},
892	"durationMinutes": {
893	"type": "number",
894	"description": "Total workout duration in minutes"
895	},
896	"equipment": {
897	"type": "array",
898	"items": { "type": "string" },
899	"description": "Required equipment"
900	},
901	"exercises": {
902	"type": "array",
903	"items": {
904	"type": "object",
905	"properties": {
906	"name": { "type": "string" },
907	"sets": { "type": "number" },
908	"reps": { "type": "string", "description": "Reps or duration (e.g. '12' or '30 seconds')" },
909	"restSeconds": { "type": "number" }
910	},
911	"required": ["name"]
912	},
913	"description": "Ordered list of exercises"
914	}
915	},
916	"required": ["routineName", "exercises"]
917	}
918	```
919	</Accordion>
920
921	<Accordion title="Repair / DIY Instructions" icon="screwdriver-wrench">
922	Extract step-by-step repair or DIY instructions from tutorial videos.
923
924	```json theme={null}
925	{
926	"type": "object",
927	"properties": {
928	"title": {
929	"type": "string",
930	"description": "What is being repaired or built"
931	},
932	"difficultyLevel": {
933	"type": "string",
934	"enum": ["easy", "moderate", "hard"],
935	"description": "Difficulty level"
936	},
937	"estimatedTimeMinutes": {
938	"type": "number",
939	"description": "Estimated time to complete"
940	},
941	"toolsRequired": {
942	"type": "array",
943	"items": { "type": "string" },
944	"description": "Tools needed"
945	},
946	"partsRequired": {
947	"type": "array",
948	"items": {
949	"type": "object",
950	"properties": {
951	"name": { "type": "string" },
952	"quantity": { "type": "number" }
953	},
954	"required": ["name"]
955	},
956	"description": "Parts or materials needed"
957	},
958	"steps": {
959	"type": "array",
960	"items": {
961	"type": "object",
962	"properties": {
963	"step": { "type": "number" },
964	"instruction": { "type": "string" },
965	"warning": { "type": "string", "description": "Safety warning if applicable" }
966	},
967	"required": ["step", "instruction"]
968	},
969	"description": "Step-by-step instructions"
970	}
971	},
972	"required": ["title", "steps"]
973	}
974	```
975	</Accordion>
976
977	<Accordion title="Life Hack / Tips" icon="wand-sparkles">
978	Extract practical tips and life hacks from advice videos.
979
980	```json theme={null}
981	{
982	"type": "object",
983	"properties": {
984	"category": {
985	"type": "string",
986	"description": "Category of tips (e.g. productivity, cooking, cleaning)"
987	},
988	"tips": {
989	"type": "array",
990	"items": {
991	"type": "object",
992	"properties": {
993	"title": {
994	"type": "string",
995	"description": "Short title for the tip"
996	},
997	"description": {
998	"type": "string",
999	"description": "Detailed explanation of the tip"
1000	},
1001	"materialsNeeded": {
1002	"type": "array",
1003	"items": { "type": "string" },
1004	"description": "Materials or items needed, if any"
1005	}
1006	},
1007	"required": ["title", "description"]
1008	},
1009	"description": "List of tips or hacks"
1010	}
1011	},
1012	"required": ["tips"]
1013	}
1014	```
1015	</Accordion>
1016
1017	<Accordion title="Product Review" icon="star">
1018	Extract structured product review data from review videos.
1019
1020	```json theme={null}
1021	{
1022	"type": "object",
1023	"properties": {
1024	"productName": {
1025	"type": "string",
1026	"description": "Name of the product being reviewed"
1027	},
1028	"brand": {
1029	"type": "string",
1030	"description": "Brand or manufacturer"
1031	},
1032	"rating": {
1033	"type": "number",
1034	"description": "Overall rating out of 10"
1035	},
1036	"pros": {
1037	"type": "array",
1038	"items": { "type": "string" },
1039	"description": "Positive aspects"
1040	},
1041	"cons": {
1042	"type": "array",
1043	"items": { "type": "string" },
1044	"description": "Negative aspects"
1045	},
1046	"verdict": {
1047	"type": "string",
1048	"description": "Final verdict or recommendation"
1049	}
1050	},
1051	"required": ["productName", "pros", "cons", "verdict"]
1052	}
1053	```
1054	</Accordion>
1055	</AccordionGroup>
1056
1057	### Response Format
1058
1059	The API always returns HTTP 202 with a job ID for asynchronous processing.
1060
1061	```typescript theme={null}
1062	{
1063	"jobId": string // Job ID for checking results
1064	}
1065	```
1066
1067	### Getting Job Results
1068
1069	Poll for results using the job ID endpoint:
1070
1071	<CodeGroup>
1072	```javascript Node.js theme={null}
1073	// Get job results
1074	const result = await supadata.extract.getResults(job.jobId);
1075
1076	if (result.status === "completed") {
1077	console.log(result.data);
1078	} else if (result.status === "failed") {
1079	console.error(result.error);
1080	} else {
1081	console.log("Job status:", result.status);
1082	}
1083	```
1084
1085	```python Python theme={null}
1086	# Get job results
1087	result = supadata.extract.get_results(job.job_id)
1088
1089	if result.status == "completed":
1090	print(result.data)
1091	elif result.status == "failed":
1092	print(result.error)
1093	else:
1094	print(f"Job status: {result.status}")
1095	```
1096
1097	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1098	curl -X GET "https://api.supadata.ai/v1/extract/123e4567-e89b-12d3-a456-426614174000" \
1099	-H "x-api-key: YOUR_API_KEY"
1100	```
1101	</CodeGroup>
1102
1103	#### Response
1104
1105	```json theme={null}
1106	{
1107	"status": "completed",
1108	"data": {
1109	"totalAppearances": 3,
1110	"appearances": [
1111	{ "timestamp": "0:12", "description": "Golden retriever runs across the park" },
1112	{ "timestamp": "1:45", "description": "Same dog catches a frisbee mid-air" },
1113	{ "timestamp": "3:20", "description": "Dog rolls over on the grass for belly rubs" }
1114	]
1115	},
1116	"schema": {
1117	"type": "object",
1118	"properties": {
1119	"totalAppearances": {
1120	"type": "number"
1121	},
1122	"appearances": {
1123	"type": "array",
1124	"items": {
1125	"type": "object",
1126	"properties": {
1127	"timestamp": { "type": "string" },
1128	"description": { "type": "string" }
1129	},
1130	"required": ["timestamp", "description"]
1131	}
1132	}
1133	},
1134	"required": ["totalAppearances", "appearances"]
1135	}
1136	}
1137	```
1138
1139	\| Field \| Type \| Description \|
1140	\| ------ \| ------ \| -------------------------------------------------------------------------------------------------- \|
1141	\| status \| string \| Job status: `queued`, `active`, `completed`, or `failed` \|
1142	\| data \| object \| Extracted data structured according to the schema. Only present when status is `completed`. \|
1143	\| schema \| object \| JSON Schema used for extraction. Only present when no schema was provided in the original request. \|
1144	\| error \| object \| Error details. Only present when status is `failed`. \|
1145
1146	#### Job Status Values
1147
1148	\| Status \| Description \|
1149	\| --------- \| ----------------------------------------------- \|
1150	\| queued \| The job is in the queue waiting to be processed \|
1151	\| active \| The job is currently being processed \|
1152	\| completed \| The job has finished and results are available \|
1153	\| failed \| The job failed due to an error \|
1154
1155	<Callout type="info">
1156	Poll the job status endpoint until the status is either "completed" or
1157	"failed". The `data` field will contain the extracted data when status is
1158	"completed", or the `error` field will contain error details when status is
1159	"failed".
1160	</Callout>
1161
1162	#### Polling Guidelines
1163
1164	* Polling interval: We recommend polling every 1 second
1165	* Job expiry: Job results are available for 1 hour after completion. After that, the endpoint will return a `404 Not Found` error. Make sure to retrieve and store results promptly after the job completes.
1166
1167	### Error Codes
1168
1169	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
1170
1171	### Supported URL Formats
1172
1173	`url` parameter supports the following:
1174
1175	* YouTube video URL, e.g. `https://www.youtube.com/watch?v=1234567890`
1176	* TikTok video URL, e.g. `https://www.tiktok.com/@username/video/1234567890`
1177	* X (Twitter) video URL, e.g. `https://x.com/username/status/1234567890`
1178	* Instagram video URL, e.g. `https://instagram.com/reel/1234567890/`
1179	* Facebook video URL, e.g.`https://www.facebook.com/reel/682865820350105/`
1180	* Publicly accessible file URL, e.g. `https://bucket.s3.eu-north-1.amazonaws.com/file.mp4`
1181
1182	### Video Accessibility
1183
1184	Only publicly accessible videos can be processed. Videos that require authentication or have restricted access will return errors:
1185
1186	* Login-required videos - Videos that require signing in
1187	* Membership/subscriber-only videos - Content behind paywalls
1188	* Private videos - Videos not publicly listed
1189	* Age-restricted videos - Content with age verification requirements
1190	* Heavily geoblocked videos - Videos available only in specific countries
1191
1192	<Tip>
1193	To verify if a video is accessible, try opening it in a browser incognito/private window without signing in. If you can watch the video, it can be processed.
1194	</Tip>
1195
1196	If the video is not accessible, the API will return:
1197
1198	* `404 Not Found` - Video does not exist or is private
1199	* `403 Forbidden` - Video requires authentication or is restricted
1200
1201	### File Support
1202
1203	When `url` is a file URL, the endpoint supports the following file formats:
1204
1205	* MP4
1206	* WEBM
1207	* MP3
1208	* FLAC
1209	* MPEG
1210	* M4A
1211	* OGG
1212	* WAV
1213
1214	The maximum file size is 200 MB. Videos longer than 55 minutes are not supported.
1215
1216	## Latency
1217
1218	Extraction always involves AI processing and returns a job ID (HTTP 202) for asynchronous handling. Processing time is correlated with video duration - the longer the video, the longer the extraction takes.
1219
1220	<Tip>
1221	Consider this latency when implementing time-outs and UX in your project. Always implement the asynchronous polling pattern to retrieve results.
1222	</Tip>
1223
1224	## Pricing
1225
1226	* 1 extraction minute = 5 credits (minimum 5 credits per request)
1227
1228	<Info>
1229	No credits are charged for checking extraction job status.
1230	</Info>
1231
1232
1233	# Metadata
1234	Source: https://docs.supadata.ai/get-metadata
1235
1236	Use this API endpoint to fetch metadata from videos and posts hosted on YouTube, TikTok, Instagram, X (Twitter) or Facebook. Supadata returns a unified schema with platform-specific fields.
1237
1238	For YouTube videos, channels, and playlists, this is part of Supadata's [YouTube API](https://supadata.ai/youtube-api) — no OAuth or quota setup required.
1239
1240	## Quick Start
1241
1242	### Request
1243
1244	<CodeGroup>
1245	```javascript Node.js theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1246	import { Supadata } from '@supadata/js';
1247
1248	const supadata = new Supadata({
1249	apiKey: 'YOUR_API_KEY',
1250	});
1251
1252	const metadata = await supadata.metadata({
1253	url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
1254	});
1255
1256	console.log(metadata)
1257	```
1258
1259	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1260	from supadata import Supadata
1261
1262	supadata = Supadata(api_key="YOUR_API_KEY")
1263
1264	metadata = supadata.metadata(
1265	url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
1266	)
1267
1268	print(metadata)
1269	```
1270
1271	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1272	curl -X GET "https://api.supadata.ai/v1/metadata?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
1273	-H "x-api-key: YOUR_API_KEY" \
1274	-H "Content-Type: application/json"
1275	```
1276	</CodeGroup>
1277
1278	### Response
1279
1280	```json theme={null}
1281	{
1282	"platform": "youtube",
1283	"type": "video",
1284	"id": "dQw4w9WgXcQ",
1285	"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
1286	"title": "Rick Astley - Never Gonna Give You Up",
1287	"description": "The official video for \"Never Gonna Give You Up\"...",
1288	"author": {
1289	"displayName": "Rick Astley",
1290	"avatarUrl": "https://yt3.ggpht.com/..."
1291	},
1292	"stats": {
1293	"views": 1234567890,
1294	"likes": 12345678,
1295	"comments": 200000,
1296	"shares": null
1297	},
1298	"media": {
1299	"type": "video",
1300	"duration": 213,
1301	"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
1302	},
1303	"tags": ["Rick Astley", "Never Gonna Give You Up", "Official Video"],
1304	"createdAt": "2009-10-25T00:00:00Z",
1305	"additionalData": {
1306	"channelId": "UCuAXFkgsw1L7xaCfnd5JJOw"
1307	}
1308	}
1309	```
1310
1311	## Specification
1312
1313	### Endpoint
1314
1315	`GET https://api.supadata.ai/v1/metadata`
1316
1317	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
1318
1319	### Query Parameters
1320
1321	\| Parameter \| Type \| Required \| Description \|
1322	\| --------- \| ------ \| -------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1323	\| url \| string \| Yes \| URL of the media to get metadata from. Must be YouTube, TikTok, Instagram, X (Twitter) or Facebook. It is recommended to encode the URL before sending it as a query parameter. \|
1324
1325	### Response Format
1326
1327	The API returns a unified metadata schema with platform-specific fields.
1328
1329	```typescript theme={null}
1330	{
1331	"platform": "youtube" \| "tiktok" \| "instagram" \| "twitter" \| "facebook",
1332	"type": "video" \| "image" \| "carousel" \| "post",
1333	"id": string,
1334	"url": string,
1335	"title": string \| null,
1336	"description": string \| null,
1337	"author": {
1338	"username": string,
1339	"displayName": string,
1340	"avatarUrl": string,
1341	"verified": boolean
1342	},
1343	"stats": {
1344	"views": number \| null,
1345	"likes": number \| null,
1346	"comments": number \| null,
1347	"shares": number \| null
1348	},
1349	"media": VideoMedia \| ImageMedia \| CarouselMedia \| PostMedia,
1350	"tags": string[],
1351	"createdAt": string,
1352	"additionalData": object // Platform-specific fields
1353	}
1354	```
1355
1356	### Error Codes
1357
1358	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
1359
1360	### Supported URL Formats
1361
1362	The metadata endpoint supports various media URLs, eg:
1363
1364	YouTube:
1365
1366	* `https://www.youtube.com/watch?v=dQw4w9WgXcQ`
1367	* `https://youtu.be/dQw4w9WgXcQ`
1368	* `https://www.youtube.com/embed/dQw4w9WgXcQ`
1369	* `https://www.youtube.com/shorts/dQw4w9WgXcQ`
1370	* `https://www.youtube.com/live/dQw4w9WgXcQ`
1371
1372	TikTok:
1373
1374	* `https://www.tiktok.com/@username/video/7234567890123456789`
1375	* `https://vm.tiktok.com/AAAAZZZZZ`
1376	* `https://m.tiktok.com/v/7234567890123456789`
1377
1378	Instagram:
1379
1380	* `https://www.instagram.com/reel/C1234567890`
1381	* `https://www.instagram.com/p/C1234567890`
1382	* `https://www.instagram.com/tv/C1234567890`
1383
1384	Twitter/X:
1385
1386	* `https://twitter.com/username/status/1234567890123456789`
1387	* `https://x.com/username/status/1234567890123456789`
1388
1389	Facebook
1390
1391	* `https://www.facebook.com/reel/682865820350105/`
1392	* `https://www.facebook.com/groups/123456789012345/permalink/987654321098765/`
1393	* `https://m.facebook.com/examplepage/posts/123123123123123/`
1394	* `https://www.facebook.com/share/p/123123123123123/`
1395	* Marketplace & Event URLs are not supported yet.
1396
1397	## Base Schema
1398
1399	All metadata responses share a common base schema regardless of platform. Here are the important details:
1400
1401	* type: Acts as a discriminator that determines the structure of the `media` field (see [Media Types](#media-types) below)
1402	* title and description: May be `null` for some platforms or content types
1403	* stats: `null` values indicate the metric is unavailable or not applicable for the platform.
1404	* createdAt: ISO 8601 formatted timestamp
1405	* additionalData: Contains platform-specific fields not included in the base schema
1406
1407	## Media Types
1408
1409	The `media` field structure varies based on the `type` discriminator:
1410
1411	* Video: `duration`, `thumbnailUrl`
1412	* Image: `url`
1413	* Carousel: `items` (array of video/image objects)
1414	* Post: no additional fields
1415
1416	## Platform-Specific Fields
1417
1418	Different platforms and media types may include additional fields in the `additionalData` object, for example:
1419
1420	* Channel information for YouTube
1421	* Music/sound information for TikTok
1422	* Retweet/quote information for X (Twitter)
1423
1424	<Info>
1425	Platform-specific fields in `additionalData` may vary and are subject to
1426	change based on platform API availability.
1427	</Info>
1428
1429	## Pricing
1430
1431	All metadata requests cost 1 credit, regardless of platform or media type.
1432
1433
1434	# Transcript
1435	Source: https://docs.supadata.ai/get-transcript
1436
1437	Use this API endpoint to fetch text transcript from a video hosted on YouTube, TikTok, Instagram, X (Twitter), Facebook or a public file URL. Supadata will fetch existing transcript or fall back to AI to create one.
1438
1439	This endpoint is the API behind Supadata's [YouTube Transcript API](https://supadata.ai/youtube-transcript-api). The same endpoint also returns transcripts for [TikTok videos](https://supadata.ai/tiktok-transcript-api), [Instagram Reels](https://supadata.ai/instagram-transcript-api), [X (Twitter) posts](https://supadata.ai/twitter-transcript-api), and [uploaded video files](https://supadata.ai/video-transcript-api).
1440
1441	## Quick Start
1442
1443	### Request
1444
1445	<CodeGroup>
1446	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1447	import { Supadata } from "@supadata/js";
1448
1449	// Initialize the client
1450	const supadata = new Supadata({
1451	apiKey: "YOUR_API_KEY",
1452	});
1453
1454	// Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file
1455	const transcriptResult = await supadata.transcript({
1456	url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
1457	lang: "en", // optional
1458	text: true, // optional: return plain text instead of timestamped chunks
1459	mode: "auto", // optional: 'native', 'auto', or 'generate'
1460	});
1461	```
1462
1463	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1464	from supadata import Supadata, SupadataError
1465
1466	# Initialize the client
1467	supadata = Supadata(api_key="YOUR_API_KEY")
1468
1469	transcript = supadata.transcript(
1470	url="https://x.com/SpaceX/status/1481651037291225113",
1471	lang="en", # Optional: preferred language
1472	text=True, # Optional: return plain text instead of timestamped chunks
1473	mode="auto" # Optional: "native", "auto", or "generate"
1474	)
1475	```
1476
1477	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1478	curl -X GET 'https://api.supadata.ai/v1/transcript?url=https://youtu.be/dQw4w9WgXcQ' \
1479	-H 'x-api-key: YOUR_API_KEY'
1480	```
1481	</CodeGroup>
1482
1483	### Response
1484
1485	```json theme={null}
1486	{
1487	"content": "Never gonna give you up, never gonna let you down...",
1488	"lang": "en",
1489	"availableLangs": ["en", "es", "zh-TW"]
1490	}
1491	```
1492
1493	## Specification
1494
1495	### Endpoint
1496
1497	`GET https://api.supadata.ai/v1/transcript`
1498
1499	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
1500
1501	### Query Parameters
1502
1503	\| Parameter \| Type \| Required \| Description \|
1504	\| --------- \| ------- \| -------- \| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1505	\| url \| string \| Yes \| URL of the video to get transcript from. Must be either YouTube, TikTok, Instagram, X (Twitter), Facebook or a public file URL. It is recommended to encode the URL before sending it as a query parameter. \|
1506	\| lang \| string \| No \| Preferred language code of the transcript (ISO 639-1). See [Languages](#languages). \|
1507	\| text \| boolean \| No \| When true, returns plain text transcript. Default: false \|
1508	\| chunkSize \| number \| No \| Maximum characters per transcript chunk (only when text=false) \|
1509	\| mode \| string \| No \| Transcript mode: `native` (only fetch existing transcript), `generate` (always generate transcript using AI), or `auto` (try native, fallback to generate if unavailable). If `url` is a file URL, mode is always `generate`. Default: `auto`. \|
1510
1511	<Info>
1512	To fetch only existing transcripts and avoid costs tied to AI generation, use
1513	`mode=native`. See <a href="#pricing">Pricing</a> for details.
1514	</Info>
1515
1516	### Response Format
1517
1518	The API can return either a transcript result directly (HTTP 200) or a job ID for asynchronous processing (HTTP 202).
1519
1520	<Info>
1521	For large videos that require processing time, the API returns HTTP 202 with a
1522	job ID. Use the `/transcript/{jobId}` endpoint to poll for results.
1523	</Info>
1524
1525	Immediate transcript response (HTTP 200):
1526
1527	When `text=true`:
1528
1529	```typescript theme={null}
1530	{
1531	"content": string,
1532	"lang": string // ISO 639-1 language code
1533	"availableLangs": string[] // List of available languages
1534	}
1535	```
1536
1537	When `text=false`:
1538
1539	```typescript theme={null}
1540	{
1541	"content": [
1542	{
1543	"text": string, // Transcript segment
1544	"offset": number, // Start time in milliseconds
1545	"duration": number, // Duration in milliseconds
1546	"lang": string // ISO 639-1 language code of chunk
1547	}
1548	],
1549	"lang": string // ISO 639-1 language code of transcript
1550	"availableLangs": string[] // List of available languages
1551	}
1552	```
1553
1554	Asynchronous job response (HTTP 202):
1555
1556	```typescript theme={null}
1557	{
1558	"jobId": string // Job ID for checking results
1559	}
1560	```
1561
1562	<Info>
1563	An HTTP 200 response with an empty `content` array (`[]`) means the
1564	transcription was successful but no speech was detected in the audio/video.
1565	Such requests are still charged according to the media duration.
1566	</Info>
1567
1568	### Getting Job Results
1569
1570	When the API returns a job ID, you can poll for results using the job ID endpoint:
1571
1572	<CodeGroup>
1573	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1574	import { Supadata } from "@supadata/js";
1575
1576	// Check if we got a transcript directly or a job ID for async processing
1577	if ("jobId" in transcriptResult) {
1578	// For large files, we get a job ID and need to poll for results
1579	const jobResult = await supadata.transcript.getJobStatus(
1580	transcriptResult.jobId
1581	);
1582	if (jobResult.status === "completed") {
1583	console.log(jobResult.content);
1584	} else if (jobResult.status === "failed") {
1585	console.error(jobResult.error);
1586	} else {
1587	console.log("Job status:", jobResult.status);
1588	}
1589	} else {
1590	// For smaller files or native transcripts, we get the result directly
1591	console.log("Transcript:", transcriptResult);
1592	}
1593	```
1594
1595	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1596	# For immediate results
1597	if hasattr(transcript, 'content'):
1598	print(f"Transcript: {transcript.content}")
1599	print(f"Language: {transcript.lang}")
1600	else:
1601	# For async processing (large files)
1602	print(f"Processing started with job ID: {transcript.job_id}")
1603	# Poll for results using existing batch.get_batch_results method
1604	```
1605
1606	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1607	curl -X GET 'https://api.supadata.ai/v1/transcript/123e4567-e89b-12d3-a456-426614174000' \
1608	-H 'x-api-key: YOUR_API_KEY'
1609	```
1610	</CodeGroup>
1611
1612	#### Response
1613
1614	```json theme={null}
1615	{
1616	"status": "completed",
1617	"content": "Never gonna give you up, never gonna let you down...",
1618	"lang": "en",
1619	"availableLangs": ["en", "es", "zh-TW"]
1620	}
1621	```
1622
1623	#### Job Status Values
1624
1625	\| Status \| Description \|
1626	\| --------- \| ----------------------------------------------- \|
1627	\| queued \| The job is in the queue waiting to be processed \|
1628	\| active \| The job is currently being processed \|
1629	\| completed \| The job has finished and results are available \|
1630	\| failed \| The job failed due to an error \|
1631
1632	<Callout type="info">
1633	Poll the job status endpoint until the status is either "completed" or
1634	"failed". The `result` field will contain the transcript data when status is
1635	"completed", or the `error` field will contain error details when status is
1636	"failed".
1637	</Callout>
1638
1639	#### Polling Guidelines
1640
1641	* Polling interval: We recommend polling every 1 second
1642	* Job expiry: Job results are available for 1 hour after completion. After that, the endpoint will return a `404 Not Found` error. Make sure to retrieve and store results promptly after the job completes.
1643
1644	### Error Codes
1645
1646	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
1647
1648	### Supported URL Formats
1649
1650	`url` parameter supports the following:
1651
1652	* YouTube video URL, e.g. `https://www.youtube.com/watch?v=1234567890`
1653	* TikTok video URL, e.g. `https://www.tiktok.com/@username/video/1234567890`
1654	* X (Twitter) video URL, e.g. `https://x.com/username/status/1234567890`
1655	* Instagram video URL, e.g. `https://instagram.com/reel/1234567890/`
1656	* Facebook video URL, e.g.`https://www.facebook.com/reel/682865820350105/`
1657	* Publicly accessible file URL, e.g. `https://bucket.s3.eu-north-1.amazonaws.com/file.mp4`
1658
1659	### Video Accessibility
1660
1661	Only publicly accessible videos can be transcribed. Videos that require authentication or have restricted access will return errors:
1662
1663	* Login-required videos - Videos that require signing in
1664	* Membership/subscriber-only videos - Content behind paywalls
1665	* Private videos - Videos not publicly listed
1666	* Age-restricted videos - Content with age verification requirements
1667	* Heavily geoblocked videos - Videos available only in specific countries
1668
1669	<Tip>
1670	To verify if a video is accessible, try opening it in a browser incognito/private window without signing in. If you can watch the video, it can be transcribed.
1671	</Tip>
1672
1673	If the video is not accessible, the API will return:
1674
1675	* `404 Not Found` - Video does not exist or is private
1676	* `403 Forbidden` - Video requires authentication or is restricted
1677
1678	### Live Streams
1679
1680	Only complete media can be transcribed. Live streams, broadcasts, and similar ongoing content are not supported, and this limitation applies to all platforms that offer them.
1681
1682	### File Transcripts
1683
1684	When `url` is a file URL, the endpoint supports the following file formats:
1685
1686	* MP4
1687	* WEBM
1688	* MP3
1689	* FLAC
1690	* MPEG
1691	* M4A
1692	* OGG
1693	* WAV
1694
1695	The maximum file size is 750 MB and the maximum duration is 12 hours. Requests for sources over these limits return an `invalid-request` error.
1696
1697	## Languages
1698
1699	The endpoint supports multiple languages. The `lang` parameter is used to specify the preferred language of the transcript. If the video does not have a transcript in the preferred language, the endpoint will return a transcript in the first available language and a list of other available languages. It is then possible to make another request to get the transcript in your chosen fallback language.
1700
1701	When `mode = generate`, the `lang` parameter is ignored and the transcript is generated in the language of the video.
1702
1703	## Latency
1704
1705	Requests for existing transcripts (eg. in `mode=native`) are resolved at normal latency. Requests that involve AI generation (eg. in `mode=generate`) can take up to 2 minutes if they do not return an asynchronous job ID earlier.
1706
1707	### AI Transcription Time
1708
1709	AI transcription time is correlated with video duration - the longer the video, the longer the transcription takes. Videos longer than 20 minutes will automatically trigger an asynchronous job, returning a job ID (HTTP 202) instead of the transcript directly. A request may also start synchronously and switch to an asynchronous job while in flight — clients should always be prepared to handle a 202 + job ID response for `mode=generate`, regardless of video length.
1710
1711	<Tip>
1712	Consider this latency when implementing time-outs and UX in your project. For example, if your app times out before receiving a response, the request will still count towards your credit usage.
1713	</Tip>
1714
1715	## Pricing
1716
1717	* 1 native transcript = 1 credit
1718	* 1 generated transcript minute = 2 credits
1719
1720	<Info>
1721	No credits are charged for checking transcription job status. 1 credit is charged when request to get a transcript returns status 206 (Transcript Unavailable).
1722	</Info>
1723
1724	### Examples
1725
1726	\| Case \| Mode \| What happens \| Credits consumed \|
1727	\| ---------------------------------------- \| ---------- \| -------------------------------------- \| ------------------------------ \|
1728	\| YouTube video without any transcript \| `auto` \| Supadata generates transcript with AI \| 2 per min of video \|
1729	\| Instagram video \| `native` \| No transcript available response (206) \| 1 \|
1730	\| Instagram video with existing transcript \| `auto` \| Supadata returns existing transcript \| 1 \|
1731	\| TikTok video \| `generate` \| Supadata generates transcript with AI \| 2 per min of video (usually 2) \|
1732
1733	### Tracking Credit Usage
1734
1735	There are two ways to check how many credits were consumed in a request:
1736
1737	1. Dashboard: The [dashboard](https://dash.supadata.ai) has a history section showing all API requests and the number of credits used for each.
1738
1739	2. Response header: Each API response includes an `x-billable-requests` header containing the number of credits consumed by that request.
1740
1741
1742	# Introduction
1743	Source: https://docs.supadata.ai/index
1744
1745	Welcome to the Supadata documentation. Our API provides powerful tools for extracting web content.
1746
1747	## Overview
1748
1749	Supadata offers four main services:
1750
1751	* Video Transcripts - Extract transcripts from YouTube, TikTok, Instagram, Facebook, X (Twitter) and video files
1752	* Media Metadata - Get social media post data like title, author and engagement metrics
1753	* Structured Data Extraction - Use AI to extract structured data from videos across all supported platforms
1754	* Web Reader - Extract content from any website, crawl pages and extract structured data
1755	* YouTube Metadata - Extract video, channel and playlist metadata
1756
1757	## Getting an API Key
1758
1759	All requests to Supadata require authentication using an API key. The same key also works with the SDKs and no-code integrations. To get your API key:
1760
1761	1. Sign up for an account at [dash.supadata.ai](https://dash.supadata.ai)
1762	2. Your API key will be generated automatically during onboarding and available in the dashboard
1763
1764	## Integrations and SDKs
1765
1766	This documentation provides examples for how to use the Supadata API and its various parameters.
1767
1768	We also offer the following SDKs and integrations:
1769
1770	* [JavaScript SDK](https://github.com/supadata-ai/js)
1771	* [Python SDK](https://github.com/supadata-ai/py)
1772	* [n8n](/integrations/n8n)
1773	* [Make](/integrations/make)
1774	* [Zapier](/integrations/zapier)
1775	* [Active Pieces](/integrations/activepieces)
1776	* [MCP](/integrations/mcp)
1777
1778	## Documentation for AI
1779
1780	If you're working with an AI assistant or vibe coding, we recommend using the "Copy Page" dropdown in top right corner of each page to get AI-ready documentation. Alternatively, give your assistant links to [llms.txt](/llms.txt) or [llms-full.txt](/llms-full.txt).
1781
1782	## Rate Limits
1783
1784	API requests are rate-limited based on your subscription plan. Current limits are shown on the [pricing page](https://supadata.ai/pricing).
1785
1786	It is possible to increase rate limits upon request.
1787
1788	## API Usage
1789
1790	### Authentication
1791
1792	All API requests require authentication using an API key. Include your API key in the request headers:
1793
1794	```bash theme={null}
1795	curl -H "x-api-key: YOUR_API_KEY" https://api.supadata.ai/v1/...
1796	```
1797
1798	<Warning>
1799	Never share your API key or commit it to version control. Use environment
1800	variables to store your API key securely. Only access the API from a secure
1801	server environment.
1802	</Warning>
1803
1804	### Base URL
1805
1806	All API endpoints use the following base URL:
1807
1808	`https://api.supadata.ai/v1`
1809
1810	### Response Format
1811
1812	All API responses are returned in JSON format.
1813
1814	# Community Resources
1815
1816	The Supadata community has created various resources and guides for using Supadata. [You can find them here](/community-resources).
1817
1818
1819	# Active Pieces
1820	Source: https://docs.supadata.ai/integrations/activepieces
1821
1822	Open-source no-code automation with Supadata integration
1823
1824	## Quick Start
1825
1826	<div>
1827	<svg aria-label="Active Pieces logo">
1828	<path />
1829	</svg>
1830
1831	<a href="https://supadata.ai/link/ap">
1832	View Active Pieces Integration →
1833	</a>
1834	</div>
1835
1836	## Installation
1837
1838	The Supadata integration is available as a piece in Active Pieces. To install:
1839
1840	1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
1841	2. Open your Active Pieces dashboard
1842	3. Navigate to Pieces and search for "Supadata"
1843	4. Click Install
1844	5. Add Supadata API key in Active Pieces connections
1845
1846	## Resources
1847
1848	* [Active Pieces Website](https://activepieces.com)
1849	* [Active Pieces Documentation](https://docs.activepieces.com)
1850	* [Active Pieces Community](https://community.activepieces.com)
1851
1852
1853	# Make
1854	Source: https://docs.supadata.ai/integrations/make
1855
1856	Build powerful visual automation workflows with Supadata and Make (formerly Integromat)
1857
1858	## Quick Start
1859
1860	<div>
1861	<img alt="Make logo" />
1862
1863	<a href="https://supadata.ai/link/make">
1864	View Make Integration →
1865	</a>
1866	</div>
1867
1868	## Installation
1869
1870	The Supadata integration is available as a module in Make. To install:
1871
1872	1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
1873	2. Open your Make dashboard
1874	3. Create a new scenario and search for "Supadata"
1875	4. Click Install
1876	5. Add Supadata API key when creating a connection
1877
1878	## Resources
1879
1880	* [Make Website](https://make.com)
1881	* [Make Documentation](https://docs.make.com)
1882	* [Make Community](https://community.make.com)
1883
1884	### Community Videos
1885
1886	<MakeVideos />
1887
1888
1889	# Supadata MCP Server — YouTube Transcripts & Web Scraping for AI Agents
1890	Source: https://docs.supadata.ai/integrations/mcp
1891
1892	Connect Claude, Cursor, and ChatGPT to YouTube transcripts and web scraping via the Supadata MCP server. Get video transcripts, scrape websites, and crawl pages directly in your AI assistant.
1893
1894	## Overview
1895
1896	The Supadata MCP (Model Context Protocol) server enables powerful web and video scraping capabilities directly within AI development environments like Cursor, Claude Desktop, and VS Code. This open-source integration allows AI models to extract transcripts, scrape web pages, and crawl entire websites to gather context.
1897
1898	## Features
1899
1900	* Multi-Platform Support: Works with YouTube, TikTok, Instagram, Twitter, and more
1901	* AI-First Design: Optimized for use with LLMs and AI assistants
1902	* Multiple Tools: Transcript extraction, web scraping, site mapping, and crawling
1903	* Easy Integration: Simple setup with popular AI tools
1904
1905	## Installation
1906
1907	### Manual Installation
1908
1909	```bash theme={null}
1910	env X_API_KEY=your-api-key npx -y @supadata/mcp
1911	```
1912
1913	## Integration Setup
1914
1915	### Claude / Claude Desktop / Cowork
1916
1917	Connect directly from Claude without manually configuring an API key.
1918
1919	1. Go to Settings → Connectors
1920	2. Click Add custom connector and enter `Supadata` as the name and `https://api.supadata.ai/mcp` as the URL. Click Add.
1921
1922	<Frame>
1923	<img />
1924	</Frame>
1925
1926	3. Click Authorize when prompted to grant MCP access.
1927
1928	<Frame>
1929	<img />
1930	</Frame>
1931
1932	### Claude Code
1933
1934	1. Add the Supadata MCP server:
1935
1936	```bash theme={null}
1937	claude mcp add --transport http supadata https://api.supadata.ai/mcp
1938	```
1939
1940	2. Run `/mcp` in Claude Code and select Authenticate for Supadata to complete the OAuth flow in your browser.
1941
1942	### ChatGPT
1943
1944	1. Go to Settings → Apps & Connectors
1945	2. Click Create to add a new connector
1946	3. Enter `Supadata` as the name and `https://api.supadata.ai/mcp` as the connector URL
1947	4. Click Save
1948
1949	To use it in a conversation, click the + icon in the composer, select More → Developer mode, and choose the Supadata connector.
1950
1951	### Cursor
1952
1953	1. Open Cursor Settings
1954	2. Navigate to MCPs & Integrations → New MCP Server
1955	3. Add new MCP server:
1956
1957	```json theme={null}
1958	{
1959	"supadata": {
1960	"command": "npx",
1961	"args": ["-y", "@supadata/mcp"],
1962	"env": {
1963	"X_API_KEY": "your-api-key"
1964	}
1965	}
1966	}
1967	```
1968
1969	### Windsurf
1970
1971	Add to `~/.windsurf/cascade/config.json`:
1972
1973	```json theme={null}
1974	{
1975	"mcpServers": {
1976	"supadata": {
1977	"command": "npx",
1978	"args": ["-y", "@supadata/mcp"],
1979	"env": {
1980	"X_API_KEY": "your-api-key"
1981	}
1982	}
1983	}
1984	}
1985	```
1986
1987	### VS Code
1988
1989	Using the MCP extension:
1990
1991	1. Install the MCP extension
1992	2. Add Supadata server configuration
1993	3. Set your API key in environment settings
1994
1995	## Configuration
1996
1997	### Environment Variables
1998
1999	* `X_API_KEY`: Your Supadata API key (required)
2000
2001	## Support
2002
2003	* [GitHub Issues](https://github.com/supadata-ai/mcp/issues)
2004	* [MCP Documentation](https://github.com/supadata-ai/mcp#readme)
2005
2006
2007	# n8n
2008	Source: https://docs.supadata.ai/integrations/n8n
2009
2010	Integrate Supadata with n8n for powerful open-source workflow automation.
2011
2012	## Quick Start
2013
2014	<div>
2015	<img alt="n8n logo" />
2016
2017	<a href="https://supadata.ai/link/n8n">
2018	View n8n Integration →
2019	</a>
2020	</div>
2021
2022	## Installation
2023
2024	The Supadata integration is available as a verified node in n8n. To install:
2025
2026	1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
2027	2. Open your n8n dashboard
2028	3. Open a workflow and search for "Supadata" when adding a node
2029	4. Click Install
2030	5. Add Supadata API key in n8n credentials
2031
2032	## Resources
2033
2034	* [n8n Website](https://n8n.io)
2035	* [n8n Documentation](https://docs.n8n.io)
2036	* [n8n Community Forum](https://community.n8n.io)
2037
2038	### Community Videos
2039
2040	<N8nVideos />
2041
2042
2043	# Node
2044	Source: https://docs.supadata.ai/integrations/node
2045
2046	Supadata Node SDK is a wrapper around the Supadata API to help you easily turn videos into transcripts and websites into markdown.
2047
2048	## Installation
2049
2050	To install the Supadata Node SDK, you can use npm (or pnpm, yarn, bun, etc.):
2051
2052	```bash Node theme={null}
2053	npm install @supadata/js
2054	```
2055
2056	## Usage
2057
2058	Get an API key from [dash.supadata.ai](https://dash.supadata.ai), then use it with the SDK.
2059
2060	Here's an example of how to use the SDK with error handling:
2061
2062	```js Node theme={null}
2063	import {
2064	Crawl,
2065	CrawlJob,
2066	JobResult,
2067	Map,
2068	Scrape,
2069	Supadata,
2070	Transcript,
2071	TranscriptOrJobId,
2072	YoutubeChannel,
2073	YoutubePlaylist,
2074	YoutubeVideo,
2075	} from "@supadata/js";
2076
2077	// Initialize the client
2078	const supadata = new Supadata({
2079	apiKey: "YOUR_API_KEY",
2080	});
2081
2082	// Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file
2083	const transcriptResult = await supadata.transcript({
2084	url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
2085	lang: "en", // optional
2086	text: true, // optional: return plain text instead of timestamped chunks
2087	mode: "auto", // optional: 'native', 'auto', or 'generate'
2088	});
2089
2090	// Check if we got a transcript directly or a job ID for async processing
2091	if ("jobId" in transcriptResult) {
2092	// For large files, we get a job ID and need to poll for results
2093	console.log(`Started transcript job: ${transcriptResult.jobId}`);
2094
2095	// Poll for job status
2096	const jobResult = await supadata.transcript.getJobStatus(
2097	transcriptResult.jobId
2098	);
2099	if (jobResult.status === "completed") {
2100	console.log("Transcript:", jobResult.content);
2101	} else if (jobResult.status === "failed") {
2102	console.error("Transcript failed:", jobResult.error);
2103	} else {
2104	console.log("Job status:", jobResult.status); // 'queued' or 'active'
2105	}
2106	} else {
2107	// For smaller files, we get the transcript directly
2108	console.log("Transcript:", transcriptResult);
2109	}
2110	```
2111
2112	### Transcripts
2113
2114	Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file
2115
2116	```js Node theme={null}
2117	import { Supadata } from "@supadata/js";
2118
2119	// Initialize the client
2120	const supadata = new Supadata({
2121	apiKey: "YOUR_API_KEY",
2122	});
2123
2124	// Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file
2125	const transcriptResult = await supadata.transcript({
2126	url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
2127	lang: "en", // optional
2128	text: true, // optional: return plain text instead of timestamped chunks
2129	mode: "auto", // optional: 'native', 'auto', or 'generate'
2130	});
2131	```
2132
2133	### YouTube
2134
2135	Get YouTube video, channel, playlist metadata.
2136
2137	```js Node theme={null}
2138	const transcript: Transcript = await supadata.youtube.transcript({
2139	url: 'https://youtu.be/dQw4w9WgXcQ',
2140	});
2141
2142	// Translate YouTube transcript
2143	const translated: Transcript = await supadata.youtube.translate({
2144	videoId: 'dQw4w9WgXcQ',
2145	lang: 'es',
2146	});
2147
2148	// Get a YouTube Video metadata
2149	const video: YoutubeVideo = await supadata.youtube.video({
2150	id: 'dQw4w9WgXcQ', // can be url or video id
2151	});
2152
2153	// Get a YouTube channel metadata
2154	const channel: YoutubeChannel = await supadata.youtube.channel({
2155	id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle
2156	});
2157
2158	// Get a list of video IDs from a YouTube channel
2159	const channelVideos: VideoIds = await supadata.youtube.channel.videos({
2160	id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle
2161	type: 'all', // 'video', 'short', 'live', 'all'
2162	limit: 10,
2163	});
2164
2165	// Get the metadata of a YouTube playlist
2166	const playlist: YoutubePlaylist = await supadata.youtube.playlist({
2167	id: 'PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI', // can be url or playlist id
2168	});
2169
2170	// Get a list of video IDs from a YouTube playlist
2171	const playlistVideos: VideoIds = await supadata.youtube.playlist.videos({
2172	id: 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc', // can be url or playlist id
2173	limit: 10,
2174	});
2175
2176	// Start a YouTube transcript batch job
2177	const transcriptBatch = await supadata.youtube.transcript.batch({
2178	videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'],
2179	// playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively
2180	// channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively
2181	lang: 'en',
2182	});
2183	console.log(`Started transcript batch job: ${transcriptBatch.jobId}`);
2184
2185	// Start a YouTube video metadata batch job
2186	const videoBatch = await supadata.youtube.video.batch({
2187	videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0', 'L_jWHffIx5E'],
2188	// playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively
2189	// channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively
2190	});
2191	console.log(`Started video batch job: ${videoBatch.jobId}`);
2192
2193	// Get results for a batch job (poll until status is 'completed' or 'failed')
2194	const batchResults = await supadata.youtube.batch.getBatchResults(
2195	transcriptBatch.jobId
2196	); // or videoBatch.jobId
2197	if (batchResults.status === 'completed') {
2198	console.log('Batch job completed:', batchResults.results);
2199	console.log('Stats:', batchResults.stats);
2200	} else {
2201	console.log('Batch job status:', batchResults.status);
2202	}
2203	```
2204
2205	### Web
2206
2207	Scrape and crawl web content.
2208
2209	```js Node theme={null}
2210	const webContent: Scrape = await supadata.web.scrape('https://supadata.ai');
2211
2212	// Map website URLs
2213	const siteMap: Map = await supadata.web.map('https://supadata.ai');
2214
2215	// Crawl website
2216	const crawl: JobId = await supadata.web.crawl({
2217	url: 'https://supadata.ai',
2218	limit: 10,
2219	});
2220
2221	// Get crawl job results
2222	const crawlResults: CrawlJob = await supadata.web.getCrawlResults(crawl.jobId);
2223	```
2224
2225	### Error Handling
2226
2227	The SDK throws `SupadataError` for API-related errors. You can catch and handle these errors as follows:
2228
2229	```js Node theme={null}
2230	import { SupadataError } from '@supadata/js';
2231
2232	try {
2233	const transcript = await supadata.youtube.transcript({
2234	videoId: 'INVALID_ID',
2235	});
2236	} catch (e) {
2237	if (e instanceof SupadataError) {
2238	console.error(e.error); // e.g., 'video-not-found'
2239	console.error(e.message); // Human readable error message
2240	console.error(e.details); // Detailed error description
2241	console.error(e.documentationUrl); // Link to error documentation (optional)
2242	}
2243	}
2244	```
2245
2246
2247	# Integrations Overview
2248	Source: https://docs.supadata.ai/integrations/overview
2249
2250	Connect Supadata to your stack with official Python and Node.js SDKs, or use no-code tools: n8n, Zapier, Make, ActivePieces, and MCP for AI agents.
2251
2252	## Official SDKs
2253
2254	<CardGroup>
2255	<Card title="Python SDK" icon="python" href="python">
2256	Explore the Python SDK for Supadata.
2257	</Card>
2258
2259	<Card title="Node SDK" icon="node" href="node">
2260	Explore the Node SDK for Supadata.
2261	</Card>
2262	</CardGroup>
2263
2264	## Integrations
2265
2266	<CardGroup>
2267	<Card title="n8n" icon={<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" d="M21.4737 5.6842c-1.1772 0-2.1663.8051-2.4468 1.8947h-2.8955c-1.235 0-2.289.893-2.492 2.111l-.1038.623a1.263 1.263 0 0 1-1.246 1.0555H11.289c-.2805-1.0896-1.2696-1.8947-2.4468-1.8947s-2.1663.8051-2.4467 1.8947H4.973c-.2805-1.0896-1.2696-1.8947-2.4468-1.8947C1.1311 9.4737 0 10.6047 0 12s1.131 2.5263 2.5263 2.5263c1.1772 0 2.1663-.8051 2.4468-1.8947h1.4223c.2804 1.0896 1.2696 1.8947 2.4467 1.8947 1.1772 0 2.1663-.8051 2.4468-1.8947h1.0008a1.263 1.263 0 0 1 1.2459 1.0555l.1038.623c.203 1.218 1.257 2.111 2.492 2.111h.3692c.2804 1.0895 1.2696 1.8947 2.4468 1.8947 1.3952 0 2.5263-1.131 2.5263-2.5263s-1.131-2.5263-2.5263-2.5263c-1.1772 0-2.1664.805-2.4468 1.8947h-.3692a1.263 1.263 0 0 1-1.246-1.0555l-.1037-.623A2.52 2.52 0 0 0 13.9607 12a2.52 2.52 0 0 0 .821-1.4794l.1038-.623a1.263 1.263 0 0 1 1.2459-1.0555h2.8955c.2805 1.0896 1.2696 1.8947 2.4468 1.8947 1.3952 0 2.5263-1.131 2.5263-2.5263s-1.131-2.5263-2.5263-2.5263m0 1.2632a1.263 1.263 0 0 1 1.2631 1.2631 1.263 1.263 0 0 1-1.2631 1.2632 1.263 1.263 0 0 1-1.2632-1.2632 1.263 1.263 0 0 1 1.2632-1.2631M2.5263 10.7368A1.263 1.263 0 0 1 3.7895 12a1.263 1.263 0 0 1-1.2632 1.2632A1.263 1.263 0 0 1 1.2632 12a1.263 1.263 0 0 1 1.2631-1.2632m6.3158 0A1.263 1.263 0 0 1 10.1053 12a1.263 1.263 0 0 1-1.2632 1.2632A1.263 1.263 0 0 1 7.579 12a1.263 1.263 0 0 1 1.2632-1.2632m10.1053 3.7895a1.263 1.263 0 0 1 1.2631 1.2632 1.263 1.263 0 0 1-1.2631 1.2631 1.263 1.263 0 0 1-1.2632-1.2631 1.263 1.263 0 0 1 1.2632-1.2632"/></svg>} href="n8n">
2268	Open-source workflow automation tool with Supadata integration.
2269	</Card>
2270
2271	<Card title="Zapier" icon={<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" d="M4.157 0A4.151 4.151 0 0 0 0 4.161v15.678A4.151 4.151 0 0 0 4.157 24h15.682A4.152 4.152 0 0 0 24 19.839V4.161A4.152 4.152 0 0 0 19.839 0H4.157Zm10.61 8.761h.03a.577.577 0 0 1 .23.038.585.585 0 0 1 .201.124.63.63 0 0 1 .162.431.612.612 0 0 1-.162.435.58.58 0 0 1-.201.128.58.58 0 0 1-.23.042.529.529 0 0 1-.235-.042.585.585 0 0 1-.332-.328.559.559 0 0 1-.038-.235.613.613 0 0 1 .17-.431.59.59 0 0 1 .405-.162Zm2.853 1.572c.03.004.061.004.095.004.325-.011.646.064.937.219.238.144.431.355.552.609.128.279.189.582.185.888v.193a2 2 0 0 1 0 .219h-2.498c.003.227.075.45.204.642a.78.78 0 0 0 .646.265.714.714 0 0 0 .484-.136.642.642 0 0 0 .23-.318l.915.257a1.398 1.398 0 0 1-.28.537c-.14.159-.321.284-.521.355a2.234 2.234 0 0 1-.836.136 1.923 1.923 0 0 1-1.001-.245 1.618 1.618 0 0 1-.665-.703 2.221 2.221 0 0 1-.227-1.036 1.95 1.95 0 0 1 .48-1.398 1.9 1.9 0 0 1 1.3-.488Zm-9.607.023c.162.004.325.026.48.079.207.065.4.174.563.314.26.302.393.692.366 1.088v2.276H8.53l-.109-.711h-.065c-.064.163-.155.31-.272.439a1.122 1.122 0 0 1-.374.264 1.023 1.023 0 0 1-.453.083 1.334 1.334 0 0 1-.866-.264.965.965 0 0 1-.329-.801.993.993 0 0 1 .076-.431 1.02 1.02 0 0 1 .242-.363 1.478 1.478 0 0 1 1.043-.303h.952v-.181a.696.696 0 0 0-.136-.454.553.553 0 0 0-.438-.154.695.695 0 0 0-.378.086.48.48 0 0 0-.193.254l-.99-.144a1.26 1.26 0 0 1 .257-.563c.14-.174.321-.302.533-.378.261-.091.54-.136.82-.129.053-.003.106-.007.163-.007Zm4.384.007c.174 0 .347.038.506.114.182.083.34.211.458.374.257.423.377.911.351 1.406a2.53 2.53 0 0 1-.355 1.448 1.148 1.148 0 0 1-1.009.517c-.204 0-.401-.045-.582-.136a1.052 1.052 0 0 1-.48-.457 1.298 1.298 0 0 1-.114-.234h-.045l.004 1.784h-1.059v-4.713h.904l.117.805h.057c.068-.208.177-.401.328-.56a1.129 1.129 0 0 1 .843-.344h.076v-.004Zm7.559.084h.903l.113.805h.053a1.37 1.37 0 0 1 .235-.484.813.813 0 0 1 .313-.242.82.82 0 0 1 .39-.076h.234v1.051h-.401a.662.662 0 0 0-.313.008.623.623 0 0 0-.272.155.663.663 0 0 0-.174.26.683.683 0 0 0-.027.314v1.875h-1.054v-3.666Zm-17.515.003h3.262v.896L3.73 13.104l.034.113h1.973l.042.9H2.4v-.9l1.931-1.754-.045-.117H2.441v-.896Zm11.815 0h1.055v3.659h-1.055V10.45Zm3.443.684.019.016a.69.69 0 0 0-.351.045.756.756 0 0 0-.287.204c-.11.155-.174.336-.189.522h1.545c-.034-.526-.257-.787-.74-.787h.003Zm-5.718.163c-.026 0-.057 0-.083.004a.78.78 0 0 0-.31.053.746.746 0 0 0-.257.189 1.016 1.016 0 0 0-.204.695v.064c-.015.257.057.507.204.711a.634.634 0 0 0 .253.196.638.638 0 0 0 .314.061.644.644 0 0 0 .578-.265c.14-.223.204-.48.189-.74a1.216 1.216 0 0 0-.181-.711.677.677 0 0 0-.503-.257Zm-4.509 1.266a.464.464 0 0 0-.268.102.373.373 0 0 0-.114.276c0 .053.008.106.027.155a.375.375 0 0 0 .087.132.576.576 0 0 0 .397.11v.004a.863.863 0 0 0 .563-.182.573.573 0 0 0 .211-.457v-.14h-.903Z"/></svg>} href="zapier">
2272	Connect Supadata with thousands of apps using automated workflows.
2273	</Card>
2274
2275	<Card title="Make" icon={<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" d="M13.38 3.498c-.27 0-.511.19-.566.465L9.85 18.986a.578.578 0 0 0 .453.678l4.095.826a.58.58 0 0 0 .682-.455l2.963-15.021a.578.578 0 0 0-.453-.678l-4.096-.826a.589.589 0 0 0-.113-.012zm-5.876.098a.576.576 0 0 0-.516.318L.062 17.697a.575.575 0 0 0 .256.774l3.733 1.877a.578.578 0 0 0 .775-.258l6.926-13.781a.577.577 0 0 0-.256-.776L7.762 3.658a.571.571 0 0 0-.258-.062zm11.74.115a.576.576 0 0 0-.576.576v15.426c0 .318.258.578.576.578h4.178a.58.58 0 0 0 .578-.578V4.287a.578.578 0 0 0-.578-.576Z"/></svg>} href="make">
2276	Visual automation platform for building complex workflows.
2277	</Card>
2278
2279	<Card title="Active Pieces" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentColor" d="M154.5 165.5c-27.9-41.8-16.7-98.5 25.1-126.4S278.1 22.4 306 63.3l190.6 282.6c27.9 41.8 16.7 98.5-25.1 126.4S373 489 345.1 448.1l-82.7-122.7c-10.2-13-32.5-11.2-45.6 1.9-11.2 11.2-13.9 38.1-17.7 62.3 0 3.7-.9 6.5-.9 10.2-1.9 15.8-7.4 30.7-16.7 44.6-30.7 45.6-92 57.6-137.6 27s-57.6-92-27-137.6c15.8-23.2 40-38.1 66-42.8 75.3-11.2 89.2-95.8 75.3-119z"/></svg>} href="activepieces">
2280	Open-source no-code automation platform.
2281	</Card>
2282
2283	<Card title="MCP" icon={<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" d="M13.85 0a4.16 4.16 0 0 0-2.95 1.217L1.456 10.66a.835.835 0 0 0 0 1.18.835.835 0 0 0 1.18 0l9.442-9.442a2.49 2.49 0 0 1 3.541 0 2.49 2.49 0 0 1 0 3.541L8.59 12.97l-.1.1a.835.835 0 0 0 0 1.18.835.835 0 0 0 1.18 0l.1-.098 7.03-7.034a2.49 2.49 0 0 1 3.542 0l.049.05a2.49 2.49 0 0 1 0 3.54l-8.54 8.54a1.96 1.96 0 0 0 0 2.755l1.753 1.753a.835.835 0 0 0 1.18 0 .835.835 0 0 0 0-1.18l-1.753-1.753a.266.266 0 0 1 0-.394l8.54-8.54a4.185 4.185 0 0 0 0-5.9l-.05-.05a4.16 4.16 0 0 0-2.95-1.218c-.2 0-.401.02-.6.048a4.17 4.17 0 0 0-1.17-3.552A4.16 4.16 0 0 0 13.85 0m0 3.333a.84.84 0 0 0-.59.245L6.275 10.56a4.186 4.186 0 0 0 0 5.902 4.186 4.186 0 0 0 5.902 0L19.16 9.48a.835.835 0 0 0 0-1.18.835.835 0 0 0-1.18 0l-6.985 6.984a2.49 2.49 0 0 1-3.54 0 2.49 2.49 0 0 1 0-3.54l6.983-6.985a.835.835 0 0 0 0-1.18.84.84 0 0 0-.59-.245"/></svg>} href="mcp">
2284	Model Context Protocol server for AI-powered scraping.
2285	</Card>
2286	</CardGroup>
2287
2288
2289	# Python
2290	Source: https://docs.supadata.ai/integrations/python
2291
2292	Supadata Python SDK is a wrapper around the Supadata API to help you easily turn videos into transcripts and websites into markdown.
2293
2294	## Installation
2295
2296	To install the Supadata Python SDK, you can use pip:
2297
2298	```bash Python theme={null}
2299	pip install supadata
2300	```
2301
2302	## Usage
2303
2304	Get an API key from [dash.supadata.ai](https://dash.supadata.ai), then use it with the SDK.
2305
2306	Here's an example of how to use the SDK:
2307
2308	```python Python theme={null}
2309	from supadata import Supadata, SupadataError
2310
2311	# Initialize the client
2312	supadata = Supadata(api_key="YOUR_API_KEY")
2313
2314	# Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter), file URLs)
2315	transcript = supadata.transcript(
2316	url="https://x.com/SpaceX/status/1481651037291225113",
2317	lang="en", # Optional: preferred language
2318	text=True, # Optional: return plain text instead of timestamped chunks
2319	mode="auto" # Optional: "native", "auto", or "generate"
2320	)
2321
2322	# For immediate results
2323	if hasattr(transcript, 'content'):
2324	print(f"Transcript: {transcript.content}")
2325	print(f"Language: {transcript.lang}")
2326	else:
2327	# For async processing (large files)
2328	print(f"Processing started with job ID: {transcript.job_id}")
2329	# Poll for results using existing batch.get_batch_results method
2330	```
2331
2332	### Transcripts
2333
2334	Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter), file URLs)
2335
2336	```python Python theme={null}
2337	from supadata import Supadata, SupadataError
2338
2339	# Initialize the client
2340	supadata = Supadata(api_key="YOUR_API_KEY")
2341
2342	transcript = supadata.transcript(
2343	url="https://x.com/SpaceX/status/1481651037291225113",
2344	lang="en", # Optional: preferred language
2345	text=True, # Optional: return plain text instead of timestamped chunks
2346	mode="auto" # Optional: "native", "auto", or "generate"
2347	)
2348	```
2349
2350	### YouTube
2351
2352	Get YouTube video, channel, playlist metadata.
2353
2354	```python Python theme={null}
2355	# Get YouTube transcript with Spanish language preference
2356	transcript = supadata.youtube.transcript(video_id="dQw4w9WgXcQ", lang="es")
2357	print(f"Got transcript {transcript.content}")
2358
2359	# Translate YouTube transcript to Spanish
2360	translated = supadata.youtube.translate(
2361	video_id="dQw4w9WgXcQ",
2362	lang="es"
2363	)
2364	print(f"Got translated transcript in {translated.lang}")
2365
2366	# Get plain text transcript
2367	text_transcript = supadata.youtube.transcript(
2368	video_id="dQw4w9WgXcQ",
2369	text=True
2370	)
2371	print(text_transcript.content)
2372
2373	# Get Video Metadata
2374	video = supadata.youtube.video(id="https://youtu.be/dQw4w9WgXcQ") # can be url or video id
2375	print(f"Video: {video}")
2376
2377	# Get Channel Metadata
2378	channel = supadata.youtube.channel(id="https://youtube.com/@RickAstleyVEVO") # can be url, channel id, handle
2379	print(f"Channel: {channel}")
2380
2381	# Get video IDs from a YouTube channel
2382	channel_videos = supadata.youtube.channel.videos(
2383	id="RickAstleyVEVO", # can be url, channel id, or handle
2384	type="all", # 'all', 'video', 'short', or 'live'
2385	limit=50
2386	)
2387	print(f"Regular videos: {channel_videos.video_ids}")
2388	print(f"Shorts: {channel_videos.short_ids}")
2389	print(f"Live: {channel_videos.live_ids}")
2390
2391	# Get Playlist metadata
2392	playlist = supadata.youtube.playlist(id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc") # can be url or playlist id
2393	print(f"Playlist: {playlist}")
2394
2395	# Get video IDs from a YouTube playlist
2396	playlist_videos = supadata.youtube.playlist.videos(
2397	id="https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # can be url or playlist id
2398	limit=50
2399	)
2400	print(f"Regular videos: {playlist_videos.video_ids}")
2401	print(f"Shorts: {playlist_videos.short_ids}")
2402	print(f"Live: {playlist_videos.live_ids}")
2403
2404	# Batch Operations
2405	transcript_batch_job = supadata.youtube.transcript.batch(
2406	video_ids=["dQw4w9WgXcQ", "xvFZjo5PgG0"],
2407	# playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # alternatively
2408	# channel_id="UC_9-kyTW8ZkZNDHQJ6FgpwQ", # alternatively
2409	lang="en", # Optional: specify preferred transcript language
2410	limit=100 # Optional: limit for playlist/channel
2411	)
2412	print(f"Started transcript batch job: {transcript_batch_job.job_id}")
2413
2414	# Start a batch job to get video metadata for a playlist
2415	video_batch_job = supadata.youtube.video.batch(
2416	playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc",
2417	limit=50
2418	)
2419	print(f"Started video metadata batch job: {video_batch_job.job_id}")
2420
2421	# Get the results of a batch job (poll until status is 'completed' or 'failed')
2422	batch_results = supadata.youtube.batch.get_batch_results(job_id=transcript_batch_job.job_id)
2423	print(f"Job status: {batch_results.status}")
2424	print(f"Stats: {batch_results.stats.succeeded}/{batch_results.stats.total} videos processed")
2425	print(f"First result: {batch_results.results[0].video_id if batch_results.results else 'No results yet'}")
2426	```
2427
2428	### Web
2429
2430	Scrape and crawl web content.
2431
2432	```python Python theme={null}
2433	web_content = supadata.web.scrape("https://supadata.ai")
2434	print(f"Page title: {web_content.name}")
2435	print(f"Page content: {web_content.content}")
2436
2437	# Map website URLs
2438	site_map = supadata.web.map("https://supadata.ai")
2439	print(f"Found {len(site_map.urls)} URLs")
2440
2441	# Start a crawl job
2442	crawl_job = supadata.web.crawl(
2443	url="https://supadata.ai",
2444	limit=100 # Optional: limit the number of pages to crawl
2445	)
2446	print(f"Started crawl job: {crawl_job.job_id}")
2447
2448	# Get crawl results
2449	# This automatically handles pagination and returns all pages
2450	try:
2451	pages = supadata.web.get_crawl_results(job_id=crawl_job.job_id)
2452	for page in pages:
2453	print(f"Crawled page: {page.url}")
2454	print(f"Page title: {page.name}")
2455	print(f"Content: {page.content}")
2456	except SupadataError as e:
2457	print(f"Crawl job failed: {e}")
2458	```
2459
2460	### Error Handling
2461
2462	The SDK uses custom `SupadataError` exceptions that provide structured error information:
2463
2464	```python Python theme={null}
2465	from supadata.errors import SupadataError
2466
2467	try:
2468	transcript = supadata.youtube.transcript(video_id="INVALID_ID")
2469	except SupadataError as error:
2470	print(f"Error code: {error.error}")
2471	print(f"Error message: {error.message}")
2472	print(f"Error details: {error.details}")
2473	if error.documentation_url:
2474	print(f"Documentation: {error.documentation_url}")
2475	```
2476
2477
2478	# Zapier
2479	Source: https://docs.supadata.ai/integrations/zapier
2480
2481	Connect Supadata with 5,000+ apps using Zapier's automated workflows
2482
2483	## Quick Start
2484
2485	<div>
2486	<img alt="Zapier logo" />
2487
2488	<a href="https://supadata.ai/link/zapier">
2489	View Zapier Integration →
2490	</a>
2491	</div>
2492
2493	## Installation
2494
2495	The Supadata integration is available as an app in Zapier. To install:
2496
2497	1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
2498	2. Open your Zapier dashboard
2499	3. Create a new Zap and search for "Supadata"
2500	4. Select Supadata from the app list
2501	5. Add Supadata API key when connecting your account
2502
2503	## Resources
2504
2505	* [Zapier Website](https://zapier.com)
2506	* [Zapier Help Center](https://help.zapier.com)
2507	* [Zapier Community](https://community.zapier.com)
2508
2509	### Community Videos
2510
2511	<ZapierVideos />
2512
2513
2514	# Crawl
2515	Source: https://docs.supadata.ai/web/crawl
2516
2517	Crawl a whole website and get content of all pages on it.
2518
2519	Crawling is a long running task. To get the content of a crawl, you first create a crawl job and then check the results of the job.
2520
2521	## Request
2522
2523	<CodeGroup>
2524	```js Node theme={null}
2525	import {
2526	Supadata,
2527	JobId
2528	} from '@supadata/js';
2529
2530	// Initialize the client
2531	const supadata = new Supadata({
2532	apiKey: 'YOUR_API_KEY',
2533	});
2534
2535	// Crawl website
2536	const crawl: JobId = await supadata.web.crawl({
2537	url: 'https://supadata.ai',
2538	limit: 10,
2539	});
2540
2541	console.log(`Started crawl job: ${crawl.jobId}`);
2542	```
2543
2544	```python Python theme={null}
2545	from supadata import Supadata
2546
2547	# Initialize the client
2548	supadata = Supadata(api_key="YOUR_API_KEY")
2549
2550	# Start a crawl job
2551	crawl_job = supadata.web.crawl(
2552	url="https://supadata.ai",
2553	limit=100 # Optional: limit the number of pages to crawl
2554	)
2555	print(f"Started crawl job: {crawl_job.job_id}")
2556	```
2557
2558	```bash cURL theme={null}
2559	curl -X POST 'https://api.supadata.ai/v1/web/crawl' \
2560	-H 'x-api-key: YOUR_API_KEY' \
2561	-H 'Content-Type: application/json' \
2562	-d '{"url": "https://supadata.ai", "limit": 100}'
2563	```
2564	</CodeGroup>
2565
2566	<Info>
2567	The crawler will follow only the child links. For example, if you crawl
2568	`https://supadata.ai/blog`, the crawler will follow links like
2569	`https://supadata.ai/blog/article-1` , but not `https://supadata.ai/about`. To
2570	crawl the whole website, provide the top URL (ie `https://supadata.ai`) as the
2571	URL to crawl.
2572	</Info>
2573
2574	## Parameters
2575
2576	\| Parameter \| Type \| Required \| Description \|
2577	\| --------- \| ------ \| -------- \| -------------------------------------------------- \|
2578	\| url \| string \| Yes \| URL of the webpage to scrape \|
2579	\| limit \| number \| No \| Maximum number of pages to crawl. Defaults to 100. \|
2580
2581	## Response
2582
2583	```json theme={null}
2584	{
2585	"jobId": "string" // The ID of the crawl job
2586	}
2587	```
2588
2589	## Results
2590
2591	After starting a crawl job, you can check the status of it. If the job is completed, you can get the results of the crawl.
2592	The results can be paginated for large crawls. In such cases, the response will contain a `next` field which you can use to get the next page of results.
2593
2594	### Crawl Job
2595
2596	<CodeGroup>
2597	```js Node theme={null}
2598	import { Supadata } from "@supadata/js";
2599
2600	const supadata = new Supadata("YOUR_API_KEY");
2601
2602	// Get crawl job results
2603	// This automatically handles pagination and returns all pages
2604	const crawlResult = await supadata.web.getCrawlResults(jobId);
2605
2606	if (crawlResult.status === "completed") {
2607	console.log("Crawl job completed successfully!");
2608	console.log(`Total pages crawled: ${crawlResult.pages.length}`);
2609
2610	// Process each page
2611	crawlResult.pages.forEach((page, index) => {
2612	console.log(`Page ${index + 1}: ${page.name}`);
2613	console.log(`URL: ${page.url}`);
2614	console.log(`Description: ${page.description}`);
2615	console.log(`Content preview: ${page.content.substring(0, 100)}...`);
2616	console.log("---");
2617	});
2618	} else if (crawlResult.status === "failed") {
2619	console.error("Crawl job failed:", crawlResult.error);
2620	} else {
2621	console.log("Job status:", crawlResult.status);
2622	}
2623	```
2624
2625	```python Python theme={null}
2626	from supadata import Supadata
2627
2628	supadata = Supadata("YOUR_API_KEY")
2629
2630	# Get crawl results
2631	# This automatically handles pagination and returns all pages
2632	crawl_result = supadata.web.get_crawl_results(job_id=job_id)
2633
2634	if crawl_result.status == "completed":
2635	print("Crawl job completed successfully!")
2636	print(f"Total pages crawled: {len(crawl_result.pages)}")
2637
2638	# Process each page
2639	for i, page in enumerate(crawl_result.pages):
2640	print(f"Page {i + 1}: {page.name}")
2641	print(f"URL: {page.url}")
2642	print(f"Description: {page.description}")
2643	print(f"Content preview: {page.content[:100]}...")
2644	print("---")
2645	elif crawl_result.status == "failed":
2646	print(f"Crawl job failed: {crawl_result.error}")
2647	else:
2648	print(f"Job status: {crawl_result.status}")
2649	```
2650
2651	```bash cURL theme={null}
2652	curl -X GET 'https://api.supadata.ai/v1/web/crawl/123e4567-e89b-12d3-a456-426614174000' \
2653	-H 'x-api-key: YOUR_API_KEY'
2654	```
2655	</CodeGroup>
2656
2657	### Crawl Results
2658
2659	```json theme={null}
2660	{
2661	"status": "string", // The status of the crawl job: 'scraping', 'completed', 'failed' or 'cancelled'
2662	"pages": [
2663	// If job is completed, contains list of pages that were crawled
2664	{
2665	"url": "string", // The URL that was scraped
2666	"content": "string", // The markdown content extracted from the URL
2667	"name": "string", // The title of the webpage
2668	"description": "string" // A description of the webpage
2669	}
2670	],
2671	"next": "string" // Large crawls will be paginated. Call this endpoint to get the next page of results
2672	}
2673	```
2674
2675	## Error Codes
2676
2677	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
2678
2679	<Info>
2680	Respect robots.txt and website terms of service when scraping web content.
2681	</Info>
2682
2683	## Pricing
2684
2685	* 1 crawl request = 1 credit
2686	* 1 crawled page = 1 credit
2687
2688
2689	# Map
2690	Source: https://docs.supadata.ai/web/map
2691
2692	Scan a whole website and get URLs on it. Can be used to create a sitemap or run a crawler to fetch content of all pages of a destination.
2693
2694	## Request
2695
2696	<CodeGroup>
2697	```js Node theme={null}
2698	import {
2699	Supadata,
2700	Map
2701	} from '@supadata/js';
2702
2703	// Initialize the client
2704	const supadata = new Supadata({
2705	apiKey: 'YOUR_API_KEY',
2706	});
2707
2708	const siteMap: Map = await supadata.web.map('https://supadata.ai');
2709
2710	```
2711
2712	```python Python theme={null}
2713	from supadata import Supadata, SupadataError
2714
2715	# Initialize the client
2716	supadata = Supadata(api_key="YOUR_API_KEY")
2717
2718	site_map = supadata.web.map("https://supadata.ai")
2719	print(f"Found {len(site_map.urls)} URLs")
2720	```
2721
2722	```bash cURL theme={null}
2723	curl 'https://api.supadata.ai/v1/web/map?url=https://example.com' \
2724	-H 'x-api-key: YOUR_API_KEY'
2725	```
2726	</CodeGroup>
2727
2728	## Parameters
2729
2730	\| Parameter \| Type \| Required \| Description \|
2731	\| --------- \| ------ \| -------- \| ------------------------- \|
2732	\| url \| string \| Yes \| URL of the website to map \|
2733
2734	## Response Format
2735
2736	```json theme={null}
2737	{
2738	"urls": [
2739	"string" // List of URLs found on the webpage
2740	]
2741	}
2742	```
2743
2744	## Pricing
2745
2746	* 1 map request = 1 credit
2747
2748
2749	# Scrape
2750	Source: https://docs.supadata.ai/web/scrape
2751
2752	Extract content from any web page using our powerful scraping API.
2753
2754	## Request
2755
2756	<CodeGroup>
2757	```js Node theme={null}
2758	import {
2759	Supadata,
2760	Scrape
2761	} from '@supadata/js';
2762
2763	// Initialize the client
2764	const supadata = new Supadata({
2765	apiKey: 'YOUR_API_KEY',
2766	});
2767
2768	const webContent: Scrape = await supadata.web.scrape('https://supadata.ai');
2769	```
2770
2771	```python Python theme={null}
2772	from supadata import Supadata, SupadataError
2773
2774	# Initialize the client
2775	supadata = Supadata(api_key="YOUR_API_KEY")
2776
2777	web_content = supadata.web.scrape("https://supadata.ai")
2778	print(f"Page title: {web_content.name}")
2779	print(f"Page content: {web_content.content}")
2780	```
2781
2782	```bash cURL theme={null}
2783	curl 'https://api.supadata.ai/v1/web/scrape?url=https://example.com' \
2784	-H 'x-api-key: YOUR_API_KEY'
2785	```
2786	</CodeGroup>
2787
2788	## Query Parameters
2789
2790	\| Parameter \| Type \| Required \| Description \|
2791	\| --------- \| ------- \| -------- \| ---------------------------------------------------------------------------------------------------------------- \|
2792	\| url \| string \| Yes \| URL of the webpage to scrape \|
2793	\| noLinks \| boolean \| No \| Whether to include Markdown links in the response \|
2794	\| lang \| string \| No \| What language to request the content in, if the website supports multiple languages. ISO 639-1 code. Default: en \|
2795
2796	## Response Format
2797
2798	```json theme={null}
2799	{
2800	"url": "string", // The URL that was scraped
2801	"content": "string", // The content extracted from the URL
2802	"name": "string", // The name of the webpage
2803	"description": "string", // A description of the webpage
2804	"ogUrl": "string", // Open Graph URL for the webpage
2805	"countCharacters": "number", // The number of characters in the content
2806	"urls": [
2807	"string" // List of URLs found on the webpage
2808	]
2809	}
2810	```
2811
2812	## Error Codes
2813
2814	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
2815
2816	<Info>
2817	Respect robots.txt and website terms of service when scraping web content.
2818	</Info>
2819
2820	## Pricing
2821
2822	* 1 transcript request = 1 credit
2823
2824
2825	# Batch
2826	Source: https://docs.supadata.ai/youtube/batch
2827
2828	Get multiple transcripts or video metadata from YouTube videos in a playlist, channel or list of URLs.
2829
2830	The batch endpoints allow you to process multiple YouTube videos in a single request. This is useful for analyzing entire playlists or channels, or for processing a list of videos. Batch operations are asynchronous and return a job ID that can be used to check the results.
2831
2832	Batch transcripts and metadata are part of Supadata's [YouTube Transcript API](https://supadata.ai/youtube-transcript-api) and [YouTube API](https://supadata.ai/youtube-api).
2833
2834	<Info>This feature is available only on paid plans.</Info>
2835
2836	## Supported Source Types
2837
2838	All batch endpoints support the following source types:
2839
2840	* List of video URLs or IDs
2841	* Playlist URL or ID
2842	* Channel URL, handle, or ID
2843
2844	## Batch Endpoints
2845
2846	### Transcript Batch
2847
2848	#### Request
2849
2850	<CodeGroup>
2851	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
2852	import {
2853	Supadata,
2854	} from '@supadata/js';
2855	// Initialize the client
2856	const supadata = new Supadata({
2857	apiKey: 'YOUR_API_KEY',
2858	});
2859
2860	// Start a YouTube transcript batch job
2861	const transcriptBatch = await supadata.youtube.transcript.batch({
2862	videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'],
2863	// playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively
2864	// channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively
2865	lang: 'en',
2866	});
2867	console.log(`Started transcript batch job: ${transcriptBatch.jobId}`);
2868	```
2869
2870	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
2871	from supadata import Supadata, SupadataError
2872
2873	# Initialize the client
2874	supadata = Supadata(api_key="YOUR_API_KEY")
2875
2876	transcript_batch_job = supadata.youtube.transcript.batch(
2877	video_ids=["dQw4w9WgXcQ", "xvFZjo5PgG0"],
2878	# playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # alternatively
2879	# channel_id="UC_9-kyTW8ZkZNDHQJ6FgpwQ", # alternatively
2880	lang="en", # Optional: specify preferred transcript language
2881	limit=100 # Optional: limit for playlist/channel
2882	)
2883	print(f"Started transcript batch job: {transcript_batch_job.job_id}")
2884	```
2885
2886	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
2887	curl -X POST 'https://api.supadata.ai/v1/youtube/transcript/batch' \
2888	-H 'x-api-key: YOUR_API_KEY' \
2889	-H 'Content-Type: application/json' \
2890	-d '{
2891	"videoIds": [
2892	"dQw4w9WgXcQ",
2893	"https://www.youtube.com/watch?v=xvFZjo5PgG0"
2894	],
2895	"lang": "en",
2896	"text": true
2897	}'
2898	```
2899	</CodeGroup>
2900
2901	#### Parameters
2902
2903	\| Parameter \| Type \| Required \| Description \|
2904	\| ---------- \| ------- \| ------------------------ \| ------------------------------------------------------------------------------------------------ \|
2905	\| videoIds \| array \| One of these is required \| Array of YouTube video IDs or URLs \|
2906	\| playlistId \| string \| One of these is required \| YouTube playlist URL or ID \|
2907	\| channelId \| string \| One of these is required \| YouTube channel URL, handle or ID \|
2908	\| limit \| number \| No \| Maximum number of videos to process (when using playlistId or channelId). Default: 10, Max: 5000 \|
2909	\| lang \| string \| No \| Preferred language code for transcripts (ISO 639-1) \|
2910	\| text \| boolean \| No \| When true, returns plain text transcript. Default: false \|
2911
2912	#### Response
2913
2914	```json theme={null}
2915	{
2916	"jobId": "123e4567-e89b-12d3-a456-426614174000"
2917	}
2918	```
2919
2920	### Video Metadata Batch
2921
2922	#### Request
2923
2924	<CodeGroup>
2925	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
2926	import {
2927	Supadata,
2928	} from '@supadata/js';
2929	// Initialize the client
2930	const supadata = new Supadata({
2931	apiKey: 'YOUR_API_KEY',
2932	});
2933
2934	// Start a YouTube video metadata batch job
2935	const videoBatch = await supadata.youtube.video.batch({
2936	playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc',
2937	limit: 20,
2938	// videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'] // alternatively
2939	// channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively
2940	});
2941	console.log(`Started video metadata batch job: ${videoBatch.jobId}`);
2942	```
2943
2944	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
2945	from supadata import Supadata
2946
2947	# Initialize the client
2948	supadata = Supadata(api_key="YOUR_API_KEY")
2949
2950	video_batch_job = supadata.youtube.video.batch(
2951	playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc",
2952	limit=20
2953	# video_ids=["dQw4w9WgXcQ", "xvFZjo5PgG0"], # alternatively
2954	# channel_id="UC_9-kyTW8ZkZNDHQJ6FgpwQ", # alternatively
2955	)
2956	print(f"Started video metadata batch job: {video_batch_job.job_id}")
2957	```
2958
2959	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
2960	curl -X POST 'https://api.supadata.ai/v1/youtube/video/batch' \
2961	-H 'x-api-key: YOUR_API_KEY' \
2962	-H 'Content-Type: application/json' \
2963	-d '{
2964	"playlistId": "PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc",
2965	"limit": 20
2966	}'
2967	```
2968	</CodeGroup>
2969
2970	#### Parameters
2971
2972	\| Parameter \| Type \| Required \| Description \|
2973	\| ---------- \| ------ \| ------------------------ \| ------------------------------------------------------------------------------------------------ \|
2974	\| videoIds \| array \| One of these is required \| Array of YouTube video IDs or URLs \|
2975	\| playlistId \| string \| One of these is required \| YouTube playlist URL or ID \|
2976	\| channelId \| string \| One of these is required \| YouTube channel URL, handle or ID \|
2977	\| limit \| number \| No \| Maximum number of videos to process (when using playlistId or channelId). Default: 10, Max: 5000 \|
2978
2979	#### Response
2980
2981	```json theme={null}
2982	{
2983	"jobId": "123e4567-e89b-12d3-a456-426614174000"
2984	}
2985	```
2986
2987	## Getting Batch Results
2988
2989	Once you've created a batch job, you can check its status and retrieve results using the job ID.
2990
2991	### Check Batch Job Status
2992
2993	`GET /v1/youtube/batch/{jobId}` - Get the status and results of a batch job.
2994
2995	#### Parameters
2996
2997	\| Parameter \| Type \| Required \| Description \|
2998	\| --------- \| ------ \| -------- \| ----------------------- \|
2999	\| jobId \| string \| Yes \| The ID of the batch job \|
3000
3001	#### Request
3002
3003	<CodeGroup>
3004	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3005	import { Supadata } from "@supadata/js";
3006
3007	const supadata = new Supadata("YOUR_API_KEY");
3008
3009	// Check the status of a batch job
3010	const batchResult = await supadata.youtube.batch.getJobStatus(jobId);
3011
3012	if (batchResult.status === "completed") {
3013	console.log("Batch job completed successfully!");
3014	console.log(`Total videos: ${batchResult.stats.total}`);
3015	console.log(`Succeeded: ${batchResult.stats.succeeded}`);
3016	console.log(`Failed: ${batchResult.stats.failed}`);
3017
3018	// Process each result
3019	batchResult.results.forEach((result, index) => {
3020	if (result.transcript) {
3021	console.log(`Video ${index + 1}: ${result.videoId}`);
3022	console.log(`Transcript: ${result.transcript.content}`);
3023	console.log(`Language: ${result.transcript.lang}`);
3024	} else if (result.errorCode) {
3025	console.log(`Video ${index + 1} failed: ${result.errorCode}`);
3026	}
3027	});
3028	} else if (batchResult.status === "failed") {
3029	console.error("Batch job failed:", batchResult.error);
3030	} else {
3031	console.log("Job status:", batchResult.status);
3032	}
3033	```
3034
3035	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3036	from supadata import Supadata
3037
3038	supadata = Supadata("YOUR_API_KEY")
3039
3040	# Check the status of a batch job
3041	batch_result = supadata.youtube.batch.get_job_status(job_id)
3042
3043	if batch_result.status == "completed":
3044	print("Batch job completed successfully!")
3045	print(f"Total videos: {batch_result.stats.total}")
3046	print(f"Succeeded: {batch_result.stats.succeeded}")
3047	print(f"Failed: {batch_result.stats.failed}")
3048
3049	# Process each result
3050	for i, result in enumerate(batch_result.results):
3051	if hasattr(result, 'transcript') and result.transcript:
3052	print(f"Video {i + 1}: {result.video_id}")
3053	print(f"Transcript: {result.transcript.content}")
3054	print(f"Language: {result.transcript.lang}")
3055	elif hasattr(result, 'error_code'):
3056	print(f"Video {i + 1} failed: {result.error_code}")
3057	elif batch_result.status == "failed":
3058	print(f"Batch job failed: {batch_result.error}")
3059	else:
3060	print(f"Job status: {batch_result.status}")
3061	```
3062
3063	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3064	curl -X GET 'https://api.supadata.ai/v1/youtube/batch/123e4567-e89b-12d3-a456-426614174000' \
3065	-H 'x-api-key: YOUR_API_KEY'
3066	```
3067	</CodeGroup>
3068
3069	#### Response
3070
3071	```json theme={null}
3072	{
3073	"status": "completed",
3074	"results": [
3075	{
3076	"videoId": "dQw4w9WgXcQ",
3077	"transcript": {
3078	"content": "Never gonna give you up, never gonna let you down...",
3079	"lang": "en",
3080	"availableLangs": ["en", "es", "fr"]
3081	}
3082	},
3083	{
3084	"videoId": "xvFZjo5PgG0",
3085	"errorCode": "transcript-unavailable"
3086	}
3087	],
3088	"stats": {
3089	"total": 2,
3090	"succeeded": 1,
3091	"failed": 1
3092	},
3093	"completedAt": "2025-04-03T06:59:53.428Z"
3094	}
3095	```
3096
3097	## Batch Job Status
3098
3099	The batch job can be in one of the following states:
3100
3101	\| Status \| Description \|
3102	\| --------- \| ----------------------------------------------- \|
3103	\| queued \| The job is in the queue waiting to be processed \|
3104	\| active \| The job is currently being processed \|
3105	\| completed \| The job has finished processing all videos \|
3106	\| failed \| The job failed due to an error \|
3107
3108	<Info>
3109	Batch jobs are processed asynchronously and may take some time to complete,
3110	especially for large playlists or channels. You should poll the job status
3111	endpoint until the status is either "completed" or "failed".
3112	</Info>
3113
3114	## Pricing
3115
3116	* 1 request to start a batch job = 1 credit
3117	* 1 video / transcript in a batch = 1 credit
3118
3119	For example, if you start a batch job with 10 videos, you will be charged 11 credits: 1 for the request and 10 for the videos.
3120
3121
3122	# Channel
3123	Source: https://docs.supadata.ai/youtube/channel
3124
3125	Use this API endpoint to fetch metadata from a YouTube channel including name, description, subscriber count, and more.
3126
3127	Channel metadata is one of the endpoints offered by [Supadata's YouTube API](https://supadata.ai/youtube-api), a simpler alternative to the official YouTube Data API.
3128
3129	## Quick Start
3130
3131	### Request
3132
3133	<CodeGroup>
3134	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3135	import {
3136	Supadata,
3137	YoutubeChannel
3138	} from '@supadata/js';
3139
3140	// Initialize the client
3141	const supadata = new Supadata({
3142	apiKey: 'YOUR_API_KEY',
3143	});
3144
3145	const channel: YoutubeChannel = await supadata.youtube.channel({
3146	id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle
3147	});
3148	```
3149
3150	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3151	from supadata import Supadata, SupadataError
3152
3153	# Initialize the client
3154	supadata = Supadata(api_key="YOUR_API_KEY")
3155
3156	channel = supadata.youtube.channel(id="https://youtube.com/@RickAstleyVEVO") # can be url, channel id, handle
3157	print(f"Channel: {channel}")
3158	```
3159
3160	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3161	curl -X GET 'https://api.supadata.ai/v1/youtube/channel?id=RickAstleyVEVO' \
3162	-H 'x-api-key: YOUR_API_KEY'
3163	```
3164	</CodeGroup>
3165
3166	### Response
3167
3168	```json theme={null}
3169	{
3170	"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
3171	"name": "Rick Astley",
3172	"description": "The official Rick Astley YouTube channel",
3173	"subscriberCount": 2000000,
3174	"videoCount": 100,
3175	"viewCount": 100,
3176	"thumbnail": "https://yt3.ggpht.com/...",
3177	"banner": "https://yt3.ggpht.com/..."
3178	}
3179	```
3180
3181	## Specification
3182
3183	### Endpoint
3184
3185	`GET https://api.supadata.ai/v1/youtube/channel`
3186
3187	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
3188
3189	### Query Parameters
3190
3191	\| Parameter \| Type \| Required \| Description \|
3192	\| --------- \| ------ \| -------- \| ------------------------------------------------------------------------------------------------------- \|
3193	\| id \| string \| Yes \| YouTube channel URL, handle or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). \|
3194
3195	## Channel Videos
3196
3197	You can also retrieve a list of video IDs from a channel using the [Channel Videos](/youtube/channel-videos) endpoint.
3198
3199	### Error Codes
3200
3201	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
3202
3203	### Supported YouTube Identifiers
3204
3205	The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details.
3206
3207	## Pricing
3208
3209	* 1 channel metadata request = 1 credit
3210
3211
3212	# Channel Videos
3213	Source: https://docs.supadata.ai/youtube/channel-videos
3214
3215	Use this API endpoint to fetch a list of video IDs from a YouTube channel.
3216
3217	## Quick Start
3218
3219	### Request
3220
3221	<CodeGroup>
3222	```js Node theme={null}
3223	import {
3224	Supadata,
3225	VideoIds
3226	} from '@supadata/js';
3227
3228	// Initialize the client
3229	const supadata = new Supadata({
3230	apiKey: 'YOUR_API_KEY',
3231	});
3232
3233	const channelVideos: VideoIds = await supadata.youtube.channel.videos({
3234	id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle
3235	type: 'all', // 'video', 'short', 'live', 'all'
3236	limit: 10,
3237	});
3238	```
3239
3240	```python Python theme={null}
3241	from supadata import Supadata, SupadataError
3242
3243	# Initialize the client
3244	supadata = Supadata(api_key="YOUR_API_KEY")
3245
3246	channel_videos = supadata.youtube.channel.videos(
3247	id="RickAstleyVEVO", # can be url, channel id, or handle
3248	type="all", # 'all', 'video', 'short', or 'live'
3249	limit=50
3250	)
3251	print(f"Regular videos: {channel_videos.video_ids}")
3252	print(f"Shorts: {channel_videos.short_ids}")
3253	print(f"Live: {channel_videos.live_ids}")
3254	```
3255
3256	```bash cURL theme={null}
3257	curl -X GET 'https://api.supadata.ai/v1/youtube/channel/videos?id=RickAstleyVEVO&limit=50' \
3258	-H 'x-api-key: YOUR_API_KEY'
3259	```
3260	</CodeGroup>
3261
3262	### Response
3263
3264	```json theme={null}
3265	{
3266	"videoIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"],
3267	"shortIds": ["xvFZjo5PgG0", "dQw4w9WgXcQ"],
3268	"liveIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"]
3269	}
3270	```
3271
3272	## Specification
3273
3274	### Endpoint
3275
3276	`GET https://api.supadata.ai/v1/youtube/channel/videos`
3277
3278	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
3279
3280	### Query Parameters
3281
3282	\| Parameter \| Type \| Required \| Description \|
3283	\| --------- \| ------ \| -------- \| ------------------------------------------------------------------------------------------------------------------- \|
3284	\| id \| string \| Yes \| YouTube channel URL, handle or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). \|
3285	\| limit \| number \| No \| Maximum number of video IDs to return. If `type` = `all`, vertical videos are prioritized. (Default: 30, Max: 5000) \|
3286	\| type \| enum \| No \| `all`, `video`, `short`, `live` (Default: `all`) \|
3287
3288	<Info>
3289	When fetching `type: all`, the limit parameter applies to vertical videos
3290	first, then Shorts and live videos. For example, if the channel has 100
3291	vertical videos and 100 Shorts, and `limit` is 150, then 100 vertical videos
3292	and 50 Shorts will be returned.
3293	</Info>
3294
3295	### Response Format
3296
3297	```typescript theme={null}
3298	{
3299	"videoIds": string[], // List of vertical YouTube video IDs
3300	"shortIds": string[], // List of Shorts IDs
3301	"liveIds": string[] // List of live video IDs
3302	}
3303	```
3304
3305	### Error Codes
3306
3307	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
3308
3309	### Supported YouTube Identifiers
3310
3311	The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details.
3312
3313	## Working with Channel Videos
3314
3315	After retrieving the list of video IDs, you can:
3316
3317	1. Get metadata for each video using the [Video Metadata](/youtube/video) endpoint
3318	2. Get transcripts for each video using the [Transcript](/get-transcript) endpoint
3319
3320	<Info>
3321	Videos are returned latest first, just like in the "Videos" tab of a YouTube
3322	channel.
3323	</Info>
3324
3325	## Pricing
3326
3327	* 1 channel videos request = 1 credit
3328
3329
3330	# Translation
3331	Source: https://docs.supadata.ai/youtube/get-transcript-translation
3332
3333	Use this API endpoint to fetch text transcript from a YouTube video in various formats and languages.
3334
3335	Translation extends Supadata's [YouTube Transcript API](https://supadata.ai/youtube-transcript-api), letting you return a video's transcript in a different language.
3336
3337	## Quick Start
3338
3339	### Request
3340
3341	<CodeGroup>
3342	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3343	import {
3344	Supadata,
3345	Transcript
3346	} from '@supadata/js';
3347
3348	// Initialize the client
3349	const supadata = new Supadata({
3350	apiKey: 'YOUR_API_KEY',
3351	});
3352
3353	const translated: Transcript = await supadata.youtube.translate({
3354	videoId: 'dQw4w9WgXcQ',
3355	lang: 'es',
3356	});
3357	```
3358
3359	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3360	from supadata import Supadata, SupadataError
3361
3362	# Initialize the client
3363	supadata = Supadata(api_key="YOUR_API_KEY")
3364
3365	translated = supadata.youtube.translate(
3366	video_id="dQw4w9WgXcQ",
3367	lang="es"
3368	)
3369	print(f"Got translated transcript in {translated.lang}")
3370	```
3371
3372	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3373	curl -X GET 'https://api.supadata.ai/v1/youtube/transcript/translate?videoId=dQw4w9WgXcQ&lang=es&text=true' \
3374	-H 'x-api-key: YOUR_API_KEY'
3375	```
3376	</CodeGroup>
3377
3378	### Response
3379
3380	```json theme={null}
3381	{
3382	"content": "Nunca voy a abandonarte, nunca voy a decepcionarte…",
3383	"lang": "es"
3384	}
3385	```
3386
3387	<Info>
3388	This endpoint has longer than usual response times. See [Latency](#latency)
3389	for more details.
3390	</Info>
3391
3392	## Specification
3393
3394	### Endpoint
3395
3396	`GET https://api.supadata.ai/v1/youtube/transcript/translate`
3397
3398	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
3399
3400	### Query Parameters
3401
3402	\| Parameter \| Type \| Required \| Description \|
3403	\| --------- \| ------- \| -------- \| --------------------------------------------------------------------------------------- \|
3404	\| url \| string \| Yes\* \| YouTube video URL. See [Supported YouTube URL Formats](#supported-youtube-url-formats). \|
3405	\| videoId \| string \| Yes\* \| YouTube video ID. Alternative to URL. \|
3406	\| lang \| string \| Yes \| ISO 639-1 language code of the translation \|
3407	\| text \| boolean \| No \| When true, returns plain text transcript. Default: false \|
3408	\| chunkSize \| number \| No \| Maximum characters per transcript chunk (only when text=false) \|
3409
3410	\* Either `url` or `videoId` must be provided
3411
3412	### Response Format
3413
3414	When `text=true`:
3415
3416	```typescript theme={null}
3417	{
3418	"content": string,
3419	"lang": string // ISO 639-1 language code
3420	}
3421	```
3422
3423	When `text=false`:
3424
3425	```typescript theme={null}
3426	{
3427	"content": [
3428	{
3429	"text": string, // Transcript segment
3430	"offset": number, // Start time in milliseconds
3431	"duration": number, // Duration in milliseconds
3432	"lang": string // ISO 639-1 language code of chunk
3433	}
3434	],
3435	"lang": string // ISO 639-1 language code of transcript
3436	}
3437	```
3438
3439	### Latency
3440
3441	Due to the duration of transcript translation tasks, the endpoint may take 20 or more seconds to complete. Please make sure to increase the request timeout in your application.
3442
3443	### Error Codes
3444
3445	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
3446
3447	### Supported YouTube URL Formats
3448
3449	`url` parameter supports various YouTube URL formats. See this [page](/youtube/supported-url-formats) for more details.
3450
3451	## Pricing
3452
3453	* 1 minute of transcript = 30 credits
3454
3455
3456	# Playlist
3457	Source: https://docs.supadata.ai/youtube/playlist
3458
3459	Use this API endpoint to fetch metadata from a YouTube playlist including title, description, video count, and more.
3460
3461	Fetching playlist details is part of the [free YouTube API](https://supadata.ai/youtube-api) from Supadata.
3462
3463	## Quick Start
3464
3465	### Request
3466
3467	<CodeGroup>
3468	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3469	import {
3470	Supadata,
3471	YoutubeChannel
3472	} from '@supadata/js';
3473
3474	// Initialize the client
3475	const supadata = new Supadata({
3476	apiKey: 'YOUR_API_KEY',
3477	});
3478
3479	const channel: YoutubeChannel = await supadata.youtube.channel({
3480	id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle
3481	});
3482	```
3483
3484	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3485	from supadata import Supadata, SupadataError
3486
3487	# Initialize the client
3488	supadata = Supadata(api_key="YOUR_API_KEY")
3489
3490	channel = supadata.youtube.channel(id="https://youtube.com/@RickAstleyVEVO") # can be url, channel id, handle
3491	print(f"Channel: {channel}")
3492	```
3493
3494	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3495	curl -X GET 'https://api.supadata.ai/v1/youtube/playlist?id=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' \
3496	-H 'x-api-key: YOUR_API_KEY'
3497	```
3498	</CodeGroup>
3499
3500	### Response
3501
3502	```json theme={null}
3503	{
3504	"id": "PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc",
3505	"title": "My Favorite Videos",
3506	"description": "A collection of my favorite videos",
3507	"videoCount": 25,
3508	"viewCount": 1000000,
3509	"lastUpdated": "2023-01-01T00:00:00.000Z",
3510	"channel": {
3511	"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
3512	"name": "Rick Astley"
3513	}
3514	}
3515	```
3516
3517	## Specification
3518
3519	### Endpoint
3520
3521	`GET https://api.supadata.ai/v1/youtube/playlist`
3522
3523	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
3524
3525	### Query Parameters
3526
3527	\| Parameter \| Type \| Required \| Description \|
3528	\| --------- \| ------ \| -------- \| ------------------------------------------------------------------------------------------------ \|
3529	\| id \| string \| Yes \| YouTube playlist URL or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). \|
3530
3531	## Playlist Videos
3532
3533	You can also retrieve a list of video IDs from a playlist using the [Playlist Videos](/youtube/playlist-videos) endpoint.
3534
3535	### Error Codes
3536
3537	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
3538
3539	### Supported YouTube Identifiers
3540
3541	The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details.
3542
3543	## Pricing
3544
3545	* 1 playlist metadata request = 1 credit
3546
3547
3548	# Playlist Videos
3549	Source: https://docs.supadata.ai/youtube/playlist-videos
3550
3551	Use this API endpoint to fetch a list of video IDs from a YouTube playlist.
3552
3553	## Quick Start
3554
3555	### Request
3556
3557	<CodeGroup>
3558	```js Node theme={null}
3559	import {
3560	Supadata,
3561	VideoIds
3562	} from '@supadata/js';
3563
3564	// Initialize the client
3565	const supadata = new Supadata({
3566	apiKey: 'YOUR_API_KEY',
3567	});
3568
3569	const playlistVideos: VideoIds = await supadata.youtube.playlist.videos({
3570	id: 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc', // can be url or playlist id
3571	limit: 10,
3572	});
3573	```
3574
3575	```python Python theme={null}
3576	from supadata import Supadata, SupadataError
3577
3578	# Initialize the client
3579	supadata = Supadata(api_key="YOUR_API_KEY")
3580
3581	playlist_videos = supadata.youtube.playlist.videos(
3582	id="https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # can be url or playlist id
3583	limit=50
3584	)
3585	print(f"Regular videos: {playlist_videos.video_ids}")
3586	print(f"Shorts: {playlist_videos.short_ids}")
3587	print(f"Live: {playlist_videos.live_ids}")
3588	```
3589
3590	```bash cURL theme={null}
3591	curl -X GET 'https://api.supadata.ai/v1/youtube/playlist/videos?id=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc&limit=20' \
3592	-H 'x-api-key: YOUR_API_KEY'
3593	```
3594	</CodeGroup>
3595
3596	### Response
3597
3598	```json theme={null}
3599	{
3600	"videoIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"],
3601	"shortIds": ["xvFZjo5PgG0", "dQw4w9WgXcQ"],
3602	"liveIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"]
3603	}
3604	```
3605
3606	## Specification
3607
3608	### Endpoint
3609
3610	`GET https://api.supadata.ai/v1/youtube/playlist/videos`
3611
3612	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
3613
3614	### Query Parameters
3615
3616	\| Parameter \| Type \| Required \| Description \|
3617	\| --------- \| ------ \| -------- \| ------------------------------------------------------------------------------------------------ \|
3618	\| id \| string \| Yes \| YouTube playlist URL or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). \|
3619	\| limit \| number \| No \| Maximum number of video IDs to return. Default: 100. Max: 5000 \|
3620
3621	### Response Format
3622
3623	```typescript theme={null}
3624	{
3625	"videoIds": string[], // List of vertical YouTube video IDs
3626	"shortIds": string[], // List of Shorts IDs
3627	"liveIds": string[] // List of live video IDs
3628	}
3629	```
3630
3631	### Error Codes
3632
3633	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
3634
3635	### Supported YouTube Identifiers
3636
3637	The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details.
3638
3639	## Working with Playlist Videos
3640
3641	After retrieving the list of video IDs, you can:
3642
3643	1. Get metadata for each video using the [Video Metadata](/youtube/video) endpoint
3644	2. Get transcripts for each video using the [Transcript](/get-transcript) endpoint
3645
3646	<Info>
3647	For large playlists, consider using the `limit` parameter to control the
3648	number of results returned.
3649	</Info>
3650
3651	## Pricing
3652
3653	* 1 playlist videos request = 1 credit
3654
3655
3656	# Search
3657	Source: https://docs.supadata.ai/youtube/search
3658
3659	Use this API endpoint to search YouTube for videos, channels, and playlists with advanced filtering options.
3660
3661	YouTube search is one of the endpoints in [Supadata's YouTube Data API alternative](https://supadata.ai/youtube-api), with no quota headaches.
3662
3663	## Quick Start
3664
3665	### Request
3666
3667	<CodeGroup>
3668	```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3669	import { Supadata } from "@supadata/js";
3670
3671	// Initialize the client
3672	const supadata = new Supadata({
3673	apiKey: "YOUR_API_KEY",
3674	});
3675
3676	const searchResults = await supadata.youtube.search({
3677	query: "never gonna give you up",
3678	type: "video", // Optional: 'video', 'channel', 'playlist', 'all' (default 'all')
3679	limit: 20, // Optional: get more than the first page of results
3680	sortBy: "views", // Optional: 'relevance', 'rating', 'date', 'views'
3681	uploadDate: "year", // Optional: 'hour', 'today', 'week', 'month', 'year'
3682	duration: "medium", // Optional: 'short', 'medium', 'long',
3683	features: ["hd", "subtitles"], // Optional
3684	});
3685
3686	console.log(`Found ${searchResults.results.length} results`);
3687	```
3688
3689	```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3690	from supadata import Supadata
3691
3692	# Initialize the client
3693	supadata = Supadata(api_key="YOUR_API_KEY")
3694
3695	search_results = supadata.youtube.search(
3696	query="never gonna give you up",
3697	type="video", # Optional: 'video', 'channel', 'playlist', 'all' (default 'all')
3698	limit=20, # Optional: get more than the first page of results
3699	sort_by="views", # Optional: 'relevance', 'rating', 'date', 'views'
3700	upload_date="year", # Optional: 'hour', 'today', 'week', 'month', 'year'
3701	duration="medium", # Optional: 'short', 'medium', 'long',
3702	features=["hd", "subtitles"], # Optional
3703	)
3704
3705	print(f"Found {len(search_results.results)} results")
3706	for result in search_results.results:
3707	print(f"{result.type}: {result.title}")
3708	```
3709
3710	```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
3711	curl -X GET 'https://api.supadata.ai/v1/youtube/search?query=never%20gonna%20give%20you%20up&type=video&limit=20&sortBy=views&uploadDate=month' \
3712	-H 'x-api-key: YOUR_API_KEY'
3713	```
3714	</CodeGroup>
3715
3716	### Response
3717
3718	```json theme={null}
3719	{
3720	"query": "Rick Astley Never Gonna Give You Up",
3721	"results": [
3722	{
3723	"type": "video",
3724	"id": "dQw4w9WgXcQ",
3725	"title": "Rick Astley - Never Gonna Give You Up (Official Video)",
3726	"description": "The official music video for Rick Astley...",
3727	"thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
3728	"duration": 213,
3729	"viewCount": 1234567890,
3730	"uploadDate": "2009-10-25T00:00:00.000Z",
3731	"channel": {
3732	"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
3733	"name": "Rick Astley",
3734	"thumbnail": "https://yt3.ggpht.com/..."
3735	}
3736	},
3737	{
3738	"type": "channel",
3739	"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
3740	"title": "Rick Astley",
3741	"description": "Official Rick Astley YouTube Channel...",
3742	"thumbnail": "https://yt3.ggpht.com/...",
3743	"subscriberCount": 2000000,
3744	"videoCount": 100
3745	},
3746	{
3747	"type": "playlist",
3748	"id": "PLrAVp4ISIlVYYbGzAY_YX30NMdvOL_PGJ",
3749	"title": "Best of Rick Astley",
3750	"description": "A collection of Rick Astley's greatest hits",
3751	"thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
3752	"videoCount": 25,
3753	"channel": {
3754	"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
3755	"name": "Rick Astley"
3756	}
3757	}
3758	],
3759	"nextPageToken": "eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"
3760	}
3761	```
3762
3763	## Specification
3764
3765	### Endpoint
3766
3767	`GET https://api.supadata.ai/v1/youtube/search`
3768
3769	Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).
3770
3771	### Query Parameters
3772
3773	\| Parameter \| Type \| Required \| Description \|
3774	\| ------------- \| ------ \| -------- \| --------------------------------------------------------------------------------------------------------------------------------------------- \|
3775	\| query \| string \| Yes \| Search query string \|
3776	\| type \| string \| No \| Filter by content type. Options: `all` (default), `video`, `channel`, `playlist`, `movie` \|
3777	\| uploadDate \| string \| No \| Filter by upload date. Options: `all` (default), `hour`, `today`, `week`, `month`, `year` \|
3778	\| duration \| string \| No \| Filter by video duration. Options: `all` (default), `short` (\<4min), `medium` (4-20min), `long` (>20min) \|
3779	\| sortBy \| string \| No \| Sort order of results. Options: `relevance` (default), `rating`, `date`, `views` \|
3780	\| features \| array \| No \| Array of special features to filter by. Options: `hd`, `subtitles`, `creative-commons`, `3d`, `live`, `4k`, `360`, `location`, `hdr`, `vr180` \|
3781	\| limit \| number \| No \| Maximum number of results to return (1-5000). When provided, API automatically paginates to fetch up to this many results \|
3782	\| nextPageToken \| string \| No \| Token for fetching the next page of results. When provided, other filter parameters are ignored \|
3783
3784	## Pagination
3785
3786	The search endpoint supports two different pagination modes depending on whether you use the `limit` parameter.
3787
3788	<Info>
3789	Supadata SDKs automatically handle pagination for you. Please use the API if
3790	you need to control pagination.
3791	</Info>
3792
3793	### Automatic Pagination (with `limit`)
3794
3795	When you provide a `limit` parameter, the API automatically handles pagination for you:
3796
3797	```bash theme={null}
3798	# Get up to 100 results automatically
3799	curl -X GET 'https://api.supadata.ai/v1/youtube/search?query=programming&limit=100' \
3800	-H 'x-api-key: YOUR_API_KEY'
3801	```
3802
3803	How it works:
3804
3805	* The API fetches multiple pages behind the scenes until it reaches your desired `limit` or runs out of results
3806	* You receive all results in a single response
3807	* Each page fetched counts as 1 credit (so requesting 100 results might consume 5+ credits if each page contains \~20 results)
3808	* No `nextPageToken` is returned since all requested results are included
3809
3810	Use this when:
3811
3812	* You need a specific number of results
3813	* You want convenience over credit control
3814	* You're building bulk data collection tools
3815
3816	### Manual Pagination (without `limit`)
3817
3818	When you don't provide a `limit` parameter, you get manual control over pagination:
3819
3820	```bash theme={null}
3821	# Get first page
3822	curl -X GET 'https://api.supadata.ai/v1/youtube/search?query=programming' \
3823	-H 'x-api-key: YOUR_API_KEY'
3824
3825	# Get next page using the token from previous response
3826	curl -X GET 'https://api.supadata.ai/v1/youtube/search?nextPageToken=TOKEN_HERE' \
3827	-H 'x-api-key: YOUR_API_KEY'
3828	```
3829
3830	How it works:
3831
3832	* You receive one page of results (\~20 items) per request
3833	* Each request consumes exactly 1 credit
3834	* A `nextPageToken` is included in the response for fetching additional pages
3835	* When using `nextPageToken`, all other filter parameters are ignored
3836
3837	Use this when:
3838
3839	* You want precise credit control
3840	* You're implementing infinite scroll or "Load More" functionality
3841	* You only need the first page of results
3842	* You're building interactive applications where users control pagination
3843
3844	### Error Codes
3845
3846	The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
3847
3848	## Pricing
3849
3850	* 1 search request = 1 credit per page of results
3851	* Using the `limit` parameter to fetch multiple pages automatically will consume credits for each page retrieved
3852
3853
3854	# Languages
3855	Source: https://docs.supadata.ai/youtube/supported-language-codes
3856
3857	Supported languages for YouTube transcripts.
3858
3859	## Supported YouTube languages
3860
3861	The `lang` parameter value designates the desired language for video transcripts. By specifying a particular language code in the Transcript API requests, you can indicate your preference for the language of the transcript.
3862
3863	If the preferred language is not available yet, a default language will be used.
3864
3865	You can use a [dedicated endpoint](/youtube/get-transcript-translation) to perform translation.
3866
3867	The following values are valid for the `lang` search parameter:
3868
3869	\| Language Code \| Language Name \|
3870	\| ------------- \| ------------------------ \|
3871	\| af \| Afrikaans \|
3872	\| ak \| Akan \|
3873	\| sq \| Albanian \|
3874	\| am \| Amharic \|
3875	\| ar \| Arabic \|
3876	\| hy \| Armenian \|
3877	\| as \| Assamese \|
3878	\| ay \| Aymara \|
3879	\| az \| Azerbaijani \|
3880	\| bn \| Bangla \|
3881	\| eu \| Basque \|
3882	\| be \| Belarusian \|
3883	\| bho \| Bhojpuri \|
3884	\| bs \| Bosnian \|
3885	\| bg \| Bulgarian \|
3886	\| my \| Burmese \|
3887	\| ca \| Catalan \|
3888	\| ceb \| Cebuano \|
3889	\| zh \| Chinese \|
3890	\| zh-HK \| Chinese (Hong Kong) \|
3891	\| zh-CN \| Chinese (China) \|
3892	\| zh-SG \| Chinese (Singapore) \|
3893	\| zh-TW \| Chinese (Taiwan) \|
3894	\| zh-Hans \| Chinese (Simplified) \|
3895	\| zh-Hant \| Chinese (Traditional) \|
3896	\| hak-TW \| Hakka Chinese (Taiwan) \|
3897	\| nan-TW \| Min Nan Chinese (Taiwan) \|
3898	\| co \| Corsican \|
3899	\| hr \| Croatian \|
3900	\| cs \| Czech \|
3901	\| da \| Danish \|
3902	\| dv \| Divehi \|
3903	\| nl \| Dutch \|
3904	\| en \| English \|
3905	\| en-US \| English (United States) \|
3906	\| eo \| Esperanto \|
3907	\| et \| Estonian \|
3908	\| ee \| Ewe \|
3909	\| fil \| Filipino \|
3910	\| fi \| Finnish \|
3911	\| fr \| French \|
3912	\| gl \| Galician \|
3913	\| lg \| Ganda \|
3914	\| ka \| Georgian \|
3915	\| de \| German \|
3916	\| el \| Greek \|
3917	\| gn \| Guarani \|
3918	\| gu \| Gujarati \|
3919	\| ht \| Haitian Creole \|
3920	\| ha \| Hausa \|
3921	\| haw \| Hawaiian \|
3922	\| iw \| Hebrew \|
3923	\| hi \| Hindi \|
3924	\| hmn \| Hmong \|
3925	\| hu \| Hungarian \|
3926	\| is \| Icelandic \|
3927	\| ig \| Igbo \|
3928	\| id \| Indonesian \|
3929	\| ga \| Irish \|
3930	\| it \| Italian \|
3931	\| ja \| Japanese \|
3932	\| jv \| Javanese \|
3933	\| kn \| Kannada \|
3934	\| kk \| Kazakh \|
3935	\| km \| Khmer \|
3936	\| rw \| Kinyarwanda \|
3937	\| ko \| Korean \|
3938	\| kri \| Krio \|
3939	\| ku \| Kurdish \|
3940	\| ky \| Kyrgyz \|
3941	\| lo \| Lao \|
3942	\| la \| Latin \|
3943	\| lv \| Latvian \|
3944	\| ln \| Lingala \|
3945	\| lt \| Lithuanian \|
3946	\| lb \| Luxembourgish \|
3947	\| mk \| Macedonian \|
3948	\| mg \| Malagasy \|
3949	\| ms \| Malay \|
3950	\| ml \| Malayalam \|
3951	\| mt \| Maltese \|
3952	\| mi \| Māori \|
3953	\| mr \| Marathi \|
3954	\| mn \| Mongolian \|
3955	\| ne \| Nepali \|
3956	\| nso \| Northern Sotho \|
3957	\| no \| Norwegian \|
3958	\| ny \| Nyanja \|
3959	\| or \| Odia \|
3960	\| om \| Oromo \|
3961	\| ps \| Pashto \|
3962	\| fa \| Persian \|
3963	\| pl \| Polish \|
3964	\| pt \| Portuguese \|
3965	\| pa \| Punjabi \|
3966	\| qu \| Quechua \|
3967	\| ro \| Romanian \|
3968	\| ru \| Russian \|
3969	\| sm \| Samoan \|
3970	\| sa \| Sanskrit \|
3971	\| gd \| Scottish Gaelic \|
3972	\| sr \| Serbian \|
3973	\| sn \| Shona \|
3974	\| sd \| Sindhi \|
3975	\| si \| Sinhala \|
3976	\| sk \| Slovak \|
3977	\| sl \| Slovenian \|
3978	\| so \| Somali \|
3979	\| st \| Southern Sotho \|
3980	\| es \| Spanish \|
3981	\| su \| Sundanese \|
3982	\| sw \| Swahili \|
3983	\| sv \| Swedish \|
3984	\| tg \| Tajik \|
3985	\| ta \| Tamil \|
3986	\| tt \| Tatar \|
3987	\| te \| Telugu \|
3988	\| th \| Thai \|
3989	\| ti \| Tigrinya \|
3990	\| ts \| Tsonga \|
3991	\| tr \| Turkish \|
3992	\| tk \| Turkmen \|
3993	\| uk \| Ukrainian \|
3994	\| ur \| Urdu \|
3995	\| ug \| Uyghur \|
3996	\| uz \| Uzbek \|
3997	\| vi \| Vietnamese \|
3998	\| cy \| Welsh \|
3999	\| fy \| Western Frisian \|
4000	\| xh \| Xhosa \|
4001	\| yi \| Yiddish \|
4002	\| yo \| Yoruba \|
4003	\| zu \| Zulu \|
4004
4005
4006	# Supported YouTube URL Formats and Examples \| Supadata Docs
4007	Source: https://docs.supadata.ai/youtube/supported-url-formats
4008
4009	Complete reference of all supported YouTube URL formats — video links, short URLs, Shorts, embeds, playlists, channels, and custom handles.
4010
4011	## Supported YouTube URL and Link Formats
4012
4013	When working with the Supadata API, you can reference any YouTube content using a variety of URL formats and link types. Whether you need to process a standard `youtube.com/watch` URL, a short `youtu.be` link, a YouTube Shorts link, or a channel handle — the API automatically detects and normalizes the input. Below is the complete reference of all supported YouTube link formats.
4014
4015	\| Content Type \| Supported Formats \| Example \|
4016	\| ------------ \| ----------------- \| ---------------------------------------------------------------------- \|
4017	\| Videos \| YouTube video URL \| `https://youtube.com/watch?v=dQw4w9WgXcQ` \|
4018	\| \| Short URL \| `http://youtu.be/dQw4w9WgXcQ` \|
4019	\| \| Shorts URL \| `https://youtube.com/shorts/dQw4w9WgXcQ` \|
4020	\| \| Embed URL \| `http://www.youtube.com/embed/dQw4w9WgXcQ` \|
4021	\| \| Video ID \| `dQw4w9WgXcQ` \|
4022	\| Playlists \| Playlist URL \| `https://youtube.com/playlist?list=PL9tY0BWXOZFuFEG_GtOBZ8-8wbkH-NVAr` \|
4023	\| \| Playlist ID \| `PL9tY0BWXOZFuFEG_GtOBZ8-8wbkH-NVAr` \|
4024	\| Channels \| Channel URL \| `https://youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw` \|
4025	\| \| Custom URL \| `https://youtube.com/c/RickAstley` \|
4026	\| \| Handle URL \| `https://youtube.com/@RickAstley` \|
4027	\| \| Channel ID \| `UCuAXFkgsw1L7xaCfnd5JJOw` \|
4028
4029	### Not supported content types:
4030
4031	* Live stream videos - not possible to fetch transcripts of currently streamed videos
4032	* Private videos - will return a 404 error
4033	* User profile links
4034
4035