Prospect demo — Supadata (unofficial)
POST/extract

Extract structured data from video

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, or a direct media file URL. Returns a job ID for asynchronous processing. Use the /extract/:jobId endpoint to poll for results.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 body fields
urlstringrequired
URL to any supported video media. Supports YouTube, TikTok, Instagram, Twitter/X, and Facebook videos, or a direct media file URL.
promptstringoptional
Natural language description of what data to extract from the video. Required if schema is not provided. Do not include JSON structure definitions here — use the "schema" field instead.
schemaobjectoptional
JSON Schema defining the structure of data to extract. Required if prompt is not provided.

7 status codes
202Job created for asynchronous processing
jobIdstringrequired
The ID of the job
400Invalid Request
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation
401Unauthorized
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation
403Forbidden
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation
404Not Found
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation
429Limit Exceeded
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation
500Internal Error
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation

Error handling

A 400 is returned: Invalid Request. A 401 is returned: Unauthorized. A 403 is returned: Forbidden. A 404 is returned: Not Found. A 429 is returned: Limit Exceeded. A 500 is returned: Internal Error.