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

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

Example Request (GET)

bash
Copy
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
Copy
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
Copy
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
Copy
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
Copy
1curl -X GET "https://api.importly.io/metadata/status?id=abc123" \
2     -H "Authorization: Bearer YOUR_API_KEY"

Status Response (Queued/Processing)

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "queued"
6  }
7}

When the job starts processing, the status changes to running:

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "running"
6  }
7}

Status Response (Completed)

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

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "completed",
6    "result": {
7      "id": "UF8uR6Z6KLc",
8      "title": "Steve Jobs' 2005 Stanford Commencement Address",
9      "description": "Drawing from some of the most pivotal points in his life, Steve Jobs urged graduates to pursue their dreams...",
10      "uploader": "Stanford",
11      "uploader_id": "@Stanford",
12      "upload_date": "20080307",
13      "duration": 905,
14      "view_count": 120000000,
15      "like_count": 3200000,
16      "thumbnail": "https://i.ytimg.com/vi/UF8uR6Z6KLc/maxresdefault.jpg",
17      "thumbnails": [
18        {
19          "url": "https://i.ytimg.com/vi/UF8uR6Z6KLc/maxresdefault.jpg",
20          "height": 720,
21          "width": 1280
22        }
23      ],
24      "formats": [
25        {
26          "format_id": "18",
27          "url": "https://example.com/video.mp4",
28          "ext": "mp4",
29          "height": 360,
30          "width": 640,
31          "fps": 25,
32          "vcodec": "avc1.42001E",
33          "acodec": "mp4a.40.2",
34          "tbr": 696.0,
35          "vbr": 568.0,
36          "abr": 128.0,
37          "filesize": 30665003,
38          "protocol": "https"
39        },
40        {
41          "format_id": "22",
42          "url": "https://example.com/video_hd.mp4",
43          "ext": "mp4",
44          "height": 720,
45          "width": 1280,
46          "fps": 25,
47          "vcodec": "avc1.64001F",
48          "acodec": "mp4a.40.2",
49          "tbr": 1154.0,
50          "vbr": 1026.0,
51          "abr": 128.0,
52          "filesize": 51234567,
53          "protocol": "https"
54        }
55      ],
56      "tags": ["stanford", "commencement", "speech"],
57      "categories": ["Education"],
58      "webpage_url": "https://www.youtube.com/watch?v=UF8uR6Z6KLc",
59      "original_url": "https://www.youtube.com/watch?v=UF8uR6Z6KLc"
60    }
61  }
62}

Status Response (Failed)

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

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "failed",
6    "message": "Failed to extract metadata from URL",
7    "code": "VIDEO_UNAVAILABLE"
8  }
9}

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

These statuses are returned synchronously when you submit the request:

• 400 Bad Request: Missing or invalid url, or the URL points to a playlist (not supported).
• 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 queuing the request.

Because metadata extraction is asynchronous, a valid submission returns 200 with status: "queued". If the URL is reachable but no media can be extracted (deleted video, geo-restricted, unsupported), the failure surfaces later from the status endpoint as status: "failed" with an error code (e.g. VIDEO_UNAVAILABLE, GEO_BLOCKED, INVALID_URL) — not as an HTTP error on submit.

429 Rate Limit Response Example

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