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

# Get Metadata

> Extract video metadata without downloading

## Overview

Extract metadata (title, duration, thumbnail, etc.) from a video URL without actually downloading the video. Useful for preview, validation, or getting video information before creating a download job.

## Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Request

<ParamField body="url" type="string" required>
  The video URL to extract metadata from
</ParamField>

## Response

<ResponseField name="title" type="string">
  Video title
</ResponseField>

<ResponseField name="duration" type="number">
  Video duration in seconds
</ResponseField>

<ResponseField name="width" type="integer">
  Video width in pixels
</ResponseField>

<ResponseField name="height" type="integer">
  Video height in pixels
</ResponseField>

<ResponseField name="extractor" type="string">
  Platform name (e.g., "YouTube", "Vimeo")
</ResponseField>

<ResponseField name="uploader" type="string">
  Channel or uploader name
</ResponseField>

<ResponseField name="thumbnail" type="string">
  URL to the video thumbnail
</ResponseField>

<ResponseField name="description" type="string">
  Video description
</ResponseField>

<ResponseField name="view_count" type="integer">
  Number of views
</ResponseField>

<ResponseField name="like_count" type="integer">
  Number of likes
</ResponseField>

<ResponseField name="upload_date" type="string">
  Upload date in YYYYMMDD format
</ResponseField>

<ResponseField name="filesize_approx" type="integer">
  Approximate file size in bytes
</ResponseField>

## Examples

<CodeGroup>
  ```bash Get Metadata theme={null}
  curl -X POST "https://api.tornadoapi.io/metadata" \
    -H "x-api-key: sk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.tornadoapi.io/metadata', {
    method: 'POST',
    headers: {
      'x-api-key': 'sk_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
    })
  });

  const metadata = await response.json();
  console.log(`Title: ${metadata.title}`);
  console.log(`Duration: ${metadata.duration}s`);
  console.log(`Resolution: ${metadata.width}x${metadata.height}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.tornadoapi.io/metadata',
      headers={'x-api-key': 'sk_your_api_key'},
      json={'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'}
  )

  metadata = response.json()
  print(f"Title: {metadata['title']}")
  print(f"Duration: {metadata['duration']}s")
  ```
</CodeGroup>

## Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
    "duration": 213.0,
    "width": 1920,
    "height": 1080,
    "extractor": "YouTube",
    "uploader": "Rick Astley",
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "description": "The official video for Never Gonna Give You Up...",
    "view_count": 1500000000,
    "like_count": 15000000,
    "upload_date": "20091025",
    "filesize_approx": 52428800
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "Failed to extract metadata",
    "details": "Video unavailable"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Missing x-api-key header"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API Key"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Failed to extract metadata"
  }
  ```
</ResponseExample>

## Use Cases

### Preview Before Download

Get video information before creating a download job to show users what they're about to download.

### Validate URLs

Check if a URL is valid and supported before adding it to a batch.

### Get Thumbnail

Extract the thumbnail URL to display in your UI without downloading the full video.

### Estimate Storage

Use `filesize_approx` to estimate storage requirements before downloading.