Metadata Endpoint

Overview

Use the /metadata endpoint to get the complete available metadata about the media at a given URL. This can help you:

Access all available information about the media (title, duration, formats, thumbnails, etc.)
Access rich metadata like upload date, uploader, description, and more
Understand what formats are available directly from the source

Parameters

Parameter	Type	Description
`url`*	`string`	Publicly accessible URL pointing to video or audio content. Can be passed as a query parameter (GET) or in the JSON body (POST).
`webhookUrl`	`string`	URL to receive a callback notification when processing is complete. Must be passed in the JSON body (POST requests only).

Note: You can pass authentication via the Authorization: Bearer <API_KEY> header for every request.

Example Request (GET)

bash
1curl -X GET "https://api.importly.io/metadata?url=https://example.com/video.mp4" \
2     -H "Authorization: Bearer YOUR_API_KEY"

Example Request (POST)

bash
1curl -X POST "https://api.importly.io/metadata" \
2     -H "Authorization: Bearer YOUR_API_KEY" \
3     -H "Content-Type: application/json" \
4     -d '{
5       "url": "https://example.com/video.mp4",
6       "webhookUrl": "https://your-app.com/webhook"
7     }'

Example Response (Initial Queue)

When you first submit a metadata request, you'll receive a job ID to track the status:

json
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "queued",
6    "message": "Metadata request queued."
7  }
8}

If you provided a webhookUrl, the message will indicate:

json
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "queued",
6    "message": "Metadata request queued. You will receive a webhook when it's complete."
7  }
8}

Checking Job Status

To check the status of your metadata request, use the /metadata/status endpoint with the job ID:

bash
1curl -X GET "https://api.importly.io/metadata/status?id=abc123" \
2     -H "Authorization: Bearer YOUR_API_KEY"

Status Response (Queued/Processing)

json
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "queued",
6    "startedAt": null,
7    "completedAt": null
8  }
9}

When the job starts processing, the status changes to running and startedAt is populated:

json
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "running",
6    "startedAt": "2025-01-15T10:30:00.000Z",
7    "completedAt": null
8  }
9}

Status Response (Completed)

When the metadata extraction is complete, the response includes the full metadata in the result field:

json
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "completed",
6    "startedAt": "2025-01-15T10:30:00.000Z",
7    "completedAt": "2025-01-15T10:30:15.000Z",
8    "result": {
9      "id": "dQw4w9WgXcQ",
10      "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
11      "description": "The official video for "Never Gonna Give You Up" by Rick Astley...",
12      "uploader": "Rick Astley",
13      "uploader_id": "@RickAstleyYT",
14      "upload_date": "20091025",
15      "duration": 212,
16      "view_count": 1500000000,
17      "like_count": 16000000,
18      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
19      "thumbnails": [
20        {
21          "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
22          "height": 720,
23          "width": 1280
24        }
25      ],
26      "formats": [
27        {
28          "format_id": "18",
29          "url": "https://example.com/video.mp4",
30          "ext": "mp4",
31          "height": 360,
32          "width": 640,
33          "fps": 25,
34          "vcodec": "avc1.42001E",
35          "acodec": "mp4a.40.2",
36          "tbr": 696.0,
37          "vbr": 568.0,
38          "abr": 128.0,
39          "filesize": 30665003,
40          "protocol": "https"
41        },
42        {
43          "format_id": "22",
44          "url": "https://example.com/video_hd.mp4",
45          "ext": "mp4",
46          "height": 720,
47          "width": 1280,
48          "fps": 25,
49          "vcodec": "avc1.64001F",
50          "acodec": "mp4a.40.2",
51          "tbr": 1154.0,
52          "vbr": 1026.0,
53          "abr": 128.0,
54          "filesize": 51234567,
55          "protocol": "https"
56        }
57      ],
58      "tags": ["music", "pop", "80s"],
59      "categories": ["Music"],
60      "webpage_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
61      "original_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
62    }
63  }
64}

Status Response (Failed)

If the metadata extraction fails, the response includes error details:

json
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "failed",
6    "message": "Failed to extract metadata from URL",
7    "code": "EXTRACTION_ERROR",
8    "startedAt": "2025-01-15T10:30:00.000Z",
9    "completedAt": "2025-01-15T10:30:05.000Z"
10  }
11}

Key Fields

title: Media title
description: Full description text
duration: Duration in seconds
uploader: Who uploaded the content
upload_date: When it was uploaded (YYYYMMDD format)
view_count, like_count: Engagement metrics
thumbnail: Primary thumbnail URL
thumbnails: Array of all available thumbnails with sizes
formats: Array of all available download formats with technical details
tags, categories: Content classification
webpage_url: Original source URL

Format Information

Each format in the formats array contains detailed technical information:

format_id: Unique identifier for this format
url: Direct download URL
ext: File extension (mp4, webm, m4a, etc.)
height/width: Video dimensions
fps: Frame rate
vcodec/acodec: Video and audio codecs
tbr/vbr/abr: Total, video, and audio bitrates
filesize: Exact file size in bytes (when available)
protocol: Download protocol (https, http, etc.)

Pricing

Each successful metadata request costs $0.01. This fixed fee is deducted from your account balance only after the metadata is successfully extracted.

Cost: $0.01 per successful request
Billing: Only charged for successful metadata extractions
Failed requests: No charge if metadata extraction fails
Balance check: Insufficient balance will result in job failure before processing

Rate Limits

The metadata endpoint has generous rate limits for efficient querying:

Request Rate: 1,000 requests per hour
Concurrency: Maximum 5 concurrent metadata requests
Status Polling: 3,600 requests per hour for status checks

All responses include rate limit headers:

X-RateLimit-Limit: Total requests allowed (1,000)
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets
X-RateLimit-Window: Time window ("1 h")

Error Handling

400 Bad Request: Missing or invalid url, or the URL points to a playlist (not supported).
404 Not Found: Couldn't locate any media info at the provided url.
401 Unauthorized: Invalid or missing API key.
429 Too Many Requests: Rate limit or concurrency limit reached. Check response headers for retry information.
500 Internal Server Error: Unexpected failure while processing the request.

429 Rate Limit Response Example

json
1{
2  "success": false,
3  "error": "Rate limit exceeded. Limit: 1000 requests per 1 h",
4  "limit": 1000,
5  "remaining": 0,
6  "reset": 1709901234000,
7  "retryAfter": 3600,
8  "endpoint": "/metadata"
9}

Best Practices

Cache Responses: If your application queries the same URL repeatedly, store the metadata to avoid unnecessary calls and save on costs.
Check Before Import: Use /metadata to avoid incurring unnecessary download costs if the URL is invalid or the content is larger than expected. The $0.01 metadata cost is much lower than potential download costs.
Parse Rich Data: Take advantage of all available metadata fields for rich user experiences.
Monitor Rate Limits: Check response headers to track usage and avoid hitting limits.
Respect Concurrency: Limit concurrent requests to 5 or fewer for optimal performance.
Implement Backoff: Use exponential backoff when receiving 429 responses.
Monitor Balance: Ensure sufficient account balance to avoid failed requests.

Endpoints Import