> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supadata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract

> 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.



## OpenAPI

````yaml v1-openapi POST /extract
openapi: 3.1.0
info:
  title: Supadata
  description: Web & Social Media Content API for Developers
  version: 1.3.0
servers:
  - url: https://api.supadata.ai/v1
security:
  - apiKeyAuth: []
paths:
  /extract:
    post:
      tags:
        - Extract
      summary: Extract structured data from video
      description: >-
        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.
      operationId: postExtract
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
      responses:
        '202':
          description: Job created for asynchronous processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobId'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: TypeScript
          label: Node.js
          source: |-
            import { Supadata } from '@supadata/js';

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

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

            // Get job results
            const result = await supadata.extract.getResults(job.jobId);
            console.log(result.data);
        - lang: Python
          label: Python
          source: |-
            from supadata import Supadata

            supadata = Supadata(api_key="YOUR_API_KEY")

            # Start extract job
            job = supadata.extract(
                url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                prompt="Extract the main topics and key takeaways"
            )

            # Get job results
            result = supadata.extract.get_results(job.job_id)
            print(result.data)
        - lang: Shell
          label: cURL - Start Extract Job
          source: |-
            curl -X POST "https://api.supadata.ai/v1/extract" \
              -H "x-api-key: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                "prompt": "Extract the main topics and key takeaways"
              }'
        - lang: Shell
          label: cURL - Get Extract Results
          source: |-
            curl -X GET "https://api.supadata.ai/v1/extract/JOB_ID" \
              -H "x-api-key: YOUR_API_KEY"
components:
  schemas:
    ExtractRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: >-
            URL to any supported video media. Supports YouTube, TikTok,
            Instagram, Twitter/X, and Facebook videos, or a direct media file
            URL.
          examples:
            - https://www.youtube.com/watch?v=dQw4w9WgXcQ
            - https://www.tiktok.com/@user/video/1234567890
            - https://www.instagram.com/reel/ABC123
        prompt:
          type: string
          description: >-
            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.
          example: Extract the main topics discussed and key takeaways
        schema:
          type: object
          additionalProperties: {}
          description: >-
            JSON Schema defining the structure of data to extract. Required if
            prompt is not provided.
          example:
            type: object
            properties:
              topics:
                type: array
                items:
                  type: string
                description: Main topics discussed
              summary:
                type: string
                description: Brief summary of the video
            required:
              - topics
              - summary
      required:
        - url
    JobId:
      type: object
      properties:
        jobId:
          type: string
          description: The ID of the job
          example: 123e4567-e89b-12d3-a456-426614174000
      required:
        - jobId
    Error:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid-request
            - internal-error
            - forbidden
            - unauthorized
            - upgrade-required
            - transcript-unavailable
            - not-found
            - limit-exceeded
          description: Error code identifying the type of error
          example: invalid-request
        message:
          type: string
          description: Human readable error message
          example: Invalid Request
        details:
          type: string
          description: Detailed error description
          example: The request is invalid or malformed
        documentationUrl:
          type: string
          description: URL to error documentation
          example: https://docs.supadata.ai/errors#invalid-request
      required:
        - error
        - message
        - details
      description: Standard error response format
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````