Extract transcripts, metadata, and structured JSON from social media videos and scrape websites into clean Markdown.
- GitHub stars
- 7
- Files
- 7
- Last commit
- Nov 3, 2026
- License
- MIT
- Allowed tools
- —
What does the supadata skill do?
supadata extracts transcripts, metadata, and structured JSON from social media videos and scrape websites into clean Markdown.
Summary generated from the skill's SKILL.md.
About the supadata skill
Converting social media videos and web pages into structured, LLM-ready data is what this skill enables. Developers and AI agents can use it to pull transcripts, captions, or subtitles from platforms like YouTube, TikTok, Instagram, X, and Facebook. It also provides access to video metadata, such as view counts and author details, and can retrieve specific information about YouTube channels or playlists.
Beyond video processing, the tool handles web scraping by turning URLs into clean Markdown or crawling entire websites to map their URL structures. For more complex tasks, it uses AI to extract structured JSON from video content based on specific prompts or schemas. The skill requires a SUPADATA_API_KEY environment variable to function. While most requests are synchronous, large files or web crawls trigger asynchronous jobs that require polling a results endpoint to retrieve the final payload.
What an agent can do with it
- 1Transcribe social media videosAn agent can extract text from a YouTube or TikTok URL to provide a written transcript.
- 2Scrape websites into MarkdownDevelopers can convert any webpage into clean Markdown format for easier processing by language models.
- 3Map website structuresThe tool can identify and list all the URLs present on a specific website.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the supadata skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the supadata skill in Claude Code
~/.claude/skills/supadata/SKILL.md
$ npx degit supadata-ai/skills/skills/supadata ~/.claude/skills/supadataInstall the supadata skill in Claude Code (project)
.claude/skills/supadata/SKILL.md
$ npx degit supadata-ai/skills/skills/supadata .claude/skills/supadataInstall the supadata skill in Codex
~/.agents/skills/supadata/SKILL.md
$ npx degit supadata-ai/skills/skills/supadata ~/.agents/skills/supadataInstall the supadata skill in Gemini CLI
~/.gemini/skills/supadata/SKILL.md
$ npx degit supadata-ai/skills/skills/supadata ~/.gemini/skills/supadataInstall the supadata skill in Claude.ai
npx degit supadata-ai/skills/skills/supadata supadata && zip -r supadata.zip supadata # claude.ai → Customize → Skills → + → Create skill → Upload a skill → supadata.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablesupadata-ai/skills/skills/supadata is public and reachablegithub.com/supadata-ai/skills/tree/HEAD/skills/supadata ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-03github.com/supadata-ai/skills/commits ↗Pass
- No download-and-run or credential theft in scripts3 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/supadata-ai/skills/blob/HEAD/skills/supadata/SKIL ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/supadata-ai/skills/blob/HEAD/skills/supadata/SKIL ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 178 linesgithub.com/supadata-ai/skills/blob/HEAD/skills/supadata/SKIL ↗Pass
SKILL.md
View on GitHubSupadata
Supadata is a single API for turning videos and web pages into LLM-ready data: transcripts, metadata, scraped Markdown, and AI-extracted JSON.
When to use this skill
Activate when the user wants any of:
- A transcript / captions / subtitles from a YouTube, TikTok, Instagram, X/Twitter, Facebook, or direct video file URL
- Metadata for a social media video/post (title, author, views, likes, etc.)
- YouTube channel or playlist info (videos, subscriber count, video lists)
- Web scraping — turn any URL into clean Markdown
- Crawling an entire website
- Mapping all URLs on a website (sitemap-style)
- AI extraction — analyze a video and return structured JSON matching a prompt or JSON Schema
- A batch of YouTube transcripts or video metadata
If the user pastes a YouTube/TikTok/IG/X/FB URL with no explicit verb, the most likely intent is "transcribe this" — confirm briefly, then use the transcript endpoint.
Setup
All endpoints require an API key passed as the x-api-key header. The skill assumes it is set as SUPADATA_API_KEY:
export SUPADATA_API_KEY="..." # get one at https://dash.supadata.ai
If the env var is missing, ask the user to set it before running any command.
Base URL: https://api.supadata.ai/v1
Endpoint decision tree
Pick the endpoint by what the user wants, not by where the URL points:
| User intent | Endpoint | Method |
|---|---|---|
| Transcript from any supported video URL (incl. YouTube) | /transcript |
GET |
| Translate a YouTube transcript | /youtube/transcript/translate |
GET |
| Batch transcripts (many YouTube videos / a playlist / a channel) | /youtube/transcript/batch |
POST |
| Metadata for any social media video/post | /metadata |
GET |
| YouTube channel info | /youtube/channel |
GET |
| YouTube playlist info | /youtube/playlist |
GET |
| List video IDs in a channel | /youtube/channel/videos |
GET |
| List video IDs in a playlist | /youtube/playlist/videos |
GET |
| Search YouTube | /youtube/search |
GET |
| Scrape one URL → Markdown | /web/scrape |
GET |
| Crawl a whole site | /web/crawl |
POST |
| Map all URLs on a site | /web/map |
GET |
| AI-extract structured data from a video | /extract |
POST |
| Account / credit usage | /me |
GET |
Note:
/youtube/transcriptand/youtube/videoare deprecated. Use/transcriptand/metadata— they accept YouTube URLs and work identically for the other platforms.
Sync vs async
Most endpoints respond synchronously with the data. Some endpoints respond with a { "jobId": "..." } and you must poll a results endpoint:
| Endpoint | Job results endpoint |
|---|---|
/transcript (when video is large; HTTP 202) |
GET /transcript/{jobId} |
/youtube/transcript/batch |
GET /youtube/batch/{jobId} |
/web/crawl |
GET /web/crawl/{jobId} |
/extract |
GET /extract/{jobId} |
Job result shape: { status: "queued" | "active" | "completed" | "failed", ...payload }. Poll every 2–5 seconds, with backoff. The helper scripts/poll-job.sh does this.
Quick recipes
Transcript from any video URL
curl -sG "https://api.supadata.ai/v1/transcript" \
-H "x-api-key: $SUPADATA_API_KEY" \
--data-urlencode "url=https://youtu.be/dQw4w9WgXcQ" \
--data-urlencode "text=true"
Response on small videos: { "content": "...", "lang": "en", "availableLangs": [...] }. On large videos the API returns HTTP 202 with { "jobId": "..." } — poll /transcript/{jobId}.
Or use the helper:
scripts/transcript.sh "https://youtu.be/dQw4w9WgXcQ"
See references/video.md for lang, mode (native / auto / generate), and chunkSize. See references/youtube.md for YouTube-specific transcript options, translation, and batch jobs.
Scrape a page to Markdown
curl -sG "https://api.supadata.ai/v1/web/scrape" \
-H "x-api-key: $SUPADATA_API_KEY" \
--data-urlencode "url=https://example.com/article"
Response: { "url": "...", "content": "# ...markdown...", "name": "Title", "description": "..." }.
Helper: scripts/scrape.sh "https://example.com"
See references/web.md for crawl, map, and noLinks / lang options.
YouTube channel / playlist / video metadata
curl -sG "https://api.supadata.ai/v1/youtube/channel" \
-H "x-api-key: $SUPADATA_API_KEY" \
--data-urlencode "id=@rickastley"
For unified social video/post metadata across platforms, see references/video.md (/metadata). For YouTube channel videos, playlist videos, search, and batch metadata, see references/youtube.md.
Extract structured data from a video
curl -sX POST "https://api.supadata.ai/v1/extract" \
-H "x-api-key: $SUPADATA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"prompt": "Extract the main topics and key takeaways"
}'
# → { "jobId": "..." }
scripts/poll-job.sh /extract <jobId>
See references/video.md for JSON Schema mode and combined prompt+schema.
Errors
Supadata returns a flat JSON error object: error is the machine-readable code, message a short title, details a longer description, and documentationUrl (optional) a link to the error docs:
{
"error": "transcript-unavailable",
"message": "Transcript Unavailable",
"details": "No transcript is available for this video",
"documentationUrl": "https://docs.supadata.ai/errors#transcript-unavailable"
}
Failed async jobs return { "status": "failed", "error": { ...same object... } } from their results endpoint.
Common codes to handle:
unauthorized(401) — bad/missing API keynot-found(404) — URL not reachable / video removedtranscript-unavailable(206/404) — fall back tomode=generate(AI transcription)limit-exceeded(429) — back off and retryupgrade-required(402) — feature not on current plan; surface to the user
When transcript-unavailable comes back from /transcript with mode=auto or native, retry with mode=generate to force AI transcription (uses more credits).
When to suggest the SDKs or the AI agent integration
If the user is building a project (not a one-off command), suggest the official SDKs:
- TypeScript/Node:
npm i @supadata/js— see https://docs.supadata.ai/integrations/node - Python:
pip install supadata— see https://docs.supadata.ai/integrations/python - AI agents (Claude, ChatGPT, Cursor), via the hosted Supadata MCP server with sign-in, no API key needed:
- Claude: https://claude.ai/directory/supadata
- ChatGPT: https://chatgpt.com/plugins/plugin_asdk_app_6ad667a8ae4881919cbe3d48dbc3d759
- Cursor: https://cursor.com/en-US/install-mcp?name=supadata&config=eyJ1cmwiOiJodHRwczovL2FwaS5zdXBhZGF0YS5haS9tY3AifQ==
- Claude Code:
claude mcp add --transport http supadata https://api.supadata.ai/mcp, then/mcp→ Authenticate - Codex, other MCP clients and the local server: https://docs.supadata.ai/integrations/mcp
The shell recipes in this skill are best for quick scripts, CI jobs, and cases where the user just wants the data piped to a file or another tool.
File map
references/video.md— universal endpoints:/transcript,/metadata,/extract(modes, languages, JSON Schema, polling)references/youtube.md— YouTube-specific: translation, batch transcripts, channel, playlist, channel/playlist videos, search, batch metadatareferences/web.md—/web/scrape,/web/crawl,/web/mapand optionsscripts/transcript.sh— fetch a transcript by URL, handle 202 job pollingscripts/scrape.sh— scrape a URL to Markdown, write to stdoutscripts/poll-job.sh— poll any async endpoint untilcompletedorfailed
Files in this skill
7supadata skill questions
How do I install the supadata skill in Claude Code?
Run npx degit supadata-ai/skills/skills/supadata ~/.claude/skills/supadata. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the supadata skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What platforms does Supadata support for video data?
It supports YouTube, TikTok, Instagram, X (Twitter), Facebook, and direct video file URLs.
How do I handle large video transcript requests?
For large videos, the API returns an HTTP 202 status with a jobId, which you must then poll using the results endpoint.
Can I turn a video into structured JSON?
Yes, you can use the AI extraction endpoint to analyze a video and return structured JSON matching a prompt or JSON Schema.