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

# Metadata

> Read a video's title, duration, uploader, thumbnails, view counts, and available formats without downloading it.

Use metadata to show a link preview, check a video's length before you pay to download it, or pick the right quality. There are two endpoints, and both cost \$0.01 and never download the media.

| Endpoint | Returns | Use it for |
| - | - | - |
| [`POST /metadata/basic`](/docs/endpoints/basic-metadata) | `title`, `duration`, `thumbnail` | Link previews and validating a URL before an import. Faster |
| [`POST /metadata`](/docs/endpoints/metadata) | Everything the source exposes: description, uploader, upload date, view and like counts, every thumbnail and format | Analytics, choosing a quality, cataloguing |

## Quick start

```bash cURL theme={null}
curl -X POST https://api.importly.io/metadata/basic \
  -H "Authorization: Bearer $IMPORTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"}'
```

```javascript Node.js theme={null}
const res = await fetch('https://api.importly.io/metadata/basic', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMPORTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw' }),
})
const { data } = await res.json()
console.log(data.jobId)
```

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

res = requests.post(
    "https://api.importly.io/metadata/basic",
    headers={"Authorization": f"Bearer {os.environ['IMPORTLY_API_KEY']}"},
    json={"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"},
)
print(res.json()["data"]["jobId"])
```

Like every endpoint, metadata runs as a job. Poll `GET /metadata/basic/status?id={jobId}` (or `/metadata/status` for full metadata), or pass a `webhookUrl`:

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "56380f26-3895-487a-8551-bc2a8b9c63ba",
    "status": "completed",
    "result": {
      "title": "Me at the zoo",
      "duration": 19,
      "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…"
    }
  }
}
```

## Full metadata fields

Full metadata is the source's own data in snake\_case, so which fields exist depends on the platform. A YouTube result has about 80 fields. These are the ones most apps use:

| Field | Meaning |
| - | - |
| `title`, `description` | Media title and full description |
| `duration` | Length in seconds |
| `uploader`, `uploader_id` | Who posted it |
| `upload_date` | Upload date as `YYYYMMDD` |
| `view_count`, `like_count` | Engagement counts, when the platform exposes them |
| `thumbnail`, `thumbnails` | Primary thumbnail URL, and every thumbnail the platform offers |
| `formats` | Every available stream, with `ext`, `height`, `width`, `fps`, codecs, bitrates, and `filesize` |
| `tags`, `categories` | The platform's classification |
| `webpage_url` | Canonical page URL |

> [!WARNING]
>
> Each entry in `formats` has the platform's own stream `url`. Those URLs are short-lived and often tied to the IP that fetched them, so they usually fail from your server. Download with [`POST /import`](/docs/features/downloads) instead.

## Without a webhook

Both endpoints also accept `GET` with the URL as a query parameter, for example `GET /metadata/basic?url=https://www.youtube.com/watch?v=jNQXAC9IVRw`. The `GET` form can't take a `webhookUrl`, so poll for the result.

## Pricing

\$0.01 per request for either endpoint. Status checks are free. See [Pricing & credits](/docs/billing.md).

> [card] [Reference: POST /metadata](/docs/endpoints/metadata.md)
>
> Full metadata, with an abridged real response.

> [card] [Reference: POST /metadata/basic](/docs/endpoints/basic-metadata.md)
>
> Title, duration, and thumbnail.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.