
Quick Start
Request
Response (HTTP 202)
Job Result
Specification
Endpoint
POST https://api.supadata.ai/v1/extract
Each request requires an x-api-key header with your API key available after signing up. Get your API key here.
Request Body
At least one of
prompt or schema must be provided. You can also provide both for maximum control over the output.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 or Metadata endpoints.Schema
Theschema parameter accepts a JSON Schema object that defines the expected structure of the extracted data. This is useful for building pipelines that need consistent, predictable output formats.
How it works
-
Prompt only: When only
promptis provided, the AI automatically generates a JSON Schema based on the prompt. The generated schema is returned in theschemafield of the response, so you can reuse it for future requests to get consistent outputs.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 explicitschema. -
Schema only: When only
schemais provided, the AI extracts data structured exactly according to the schema. - 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.
Example with schema
Schema rules
Schemas are checked before the job is created. If a schema can’t be used,POST /extract answers 400 invalid-request right away with a details message saying what to change, and no credits are used.
- Is valid JSON Schema (draft-07).
- Is nested no more than 8 levels deep.
- Fits the AI model’s output-format limit (see below).
Avoid size bounds:
maxItems, minItems, maxLength, minLength
The AI model expands every allowed array item and string length into its output format. Large bounds make that format too big, and the request is rejected — most often on arrays of objects:
The total size also counts: many properties, long property names, deep nesting and very long
enum lists all add up. If you need a limit, describe it instead of enforcing it in the schema:
Schema Examples
Copy any of these schemas and use them directly in your requests.Recipe Extraction
Recipe Extraction
Extract cooking recipes with ingredients, steps and nutritional info.
Video Chapters
Video Chapters
Extract timestamped chapters and sections from a video.
Key Takeaways
Key Takeaways
Extract main points, takeaways and action items from educational or business content.
Fitness Routine
Fitness Routine
Extract workout routines with exercises, sets, reps and rest periods.
Repair / DIY Instructions
Repair / DIY Instructions
Extract step-by-step repair or DIY instructions from tutorial videos.
Life Hack / Tips
Life Hack / Tips
Extract practical tips and life hacks from advice videos.
Product Review
Product Review
Extract structured product review data from review videos.
Response Format
The API always returns HTTP 202 with a job ID for asynchronous processing.Getting Job Results
Poll for results using the job ID endpoint:Response
Job Status Values
Poll the job status endpoint until the status is either “completed” or
“failed”. The
data field will contain the extracted data when status is
“completed”, or the error field will contain error details when status is
“failed”.Polling Guidelines
- Polling interval: We recommend polling every 1 second
- Job expiry: Job results are available for 1 hour after completion. After that, the endpoint will return a
404 Not Founderror. Make sure to retrieve and store results promptly after the job completes.
Error Codes
The API returns HTTP status codes and error codes. See this page for more details.Supported URL Formats
url parameter supports the following:
- YouTube video URL, e.g.
https://www.youtube.com/watch?v=1234567890 - TikTok video URL, e.g.
https://www.tiktok.com/@username/video/1234567890 - X (Twitter) video URL, e.g.
https://x.com/username/status/1234567890 - Instagram video URL, e.g.
https://instagram.com/reel/1234567890/ - Facebook video URL, e.g.
https://www.facebook.com/reel/682865820350105/ - Publicly accessible file URL, e.g.
https://bucket.s3.eu-north-1.amazonaws.com/file.mp4
Video Accessibility
Only publicly accessible videos can be processed. Videos that require authentication or have restricted access will return errors:- Login-required videos - Videos that require signing in
- Membership/subscriber-only videos - Content behind paywalls
- Private videos - Videos not publicly listed
- Age-restricted videos - Content with age verification requirements
- Heavily geoblocked videos - Videos available only in specific countries
404 Not Found- Video does not exist or is private403 Forbidden- Video requires authentication or is restricted
File Support
Whenurl is a file URL, it must point to a video file that can be downloaded without signing in. Supported formats: MP4, MOV and WEBM. Audio-only files (MP3, WAV, M4A, …) have nothing to analyze visually and are rejected with 400 invalid-request — use the Transcript endpoint for those.
Limits
The whole video is analyzed, from the first to the last second, on every platform. How densely it is sampled depends on the length:
Larger videos are analyzed at reduced resolution (360p). Large on-screen text, slides, people, objects and actions are recognized reliably; very small text may not be legible, especially in long videos.
Example error for a video over the limit:
Latency
Extraction always involves AI processing and returns a job ID (HTTP 202) for asynchronous handling. Processing time grows with video duration: short social videos typically complete in 10–30 seconds, while hour-long videos can take a few minutes.Pricing
- 5 credits per started minute of video, on every platform and for file URLs (minimum 5 credits per request)
No credits are charged for checking extraction job status.