Importly

Basic Metadata Endpoint

Overview

Use the /metadata/basic endpoint to quickly retrieve essential metadata about media at a given URL. This lightweight endpoint returns only the core information you need:

  • title: Media title
  • duration: Duration in seconds
  • thumbnail: Primary thumbnail URL

This is ideal when you only need basic information for display purposes and don't require the full metadata (formats, tags, descriptions, etc.) returned by the full metadata endpoint.

Parameters

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

webhookUrlstring

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/basic?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/basic" \
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 basic 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": "Basic 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": "Basic metadata request queued. You will receive a webhook when it's complete."
7  }
8}

Checking Job Status

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

bash
1curl -X GET "https://api.importly.io/metadata/basic/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  }
7}

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

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

Status Response (Completed)

When the basic metadata extraction is complete, the response includes the result:

json
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "completed",
6    "result": {
7      "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
8      "duration": 212,
9      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
10    }
11  }
12}

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  }
9}

Pricing

Each successful basic 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 basic metadata endpoint shares rate limits with the full metadata endpoint:

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

Best Practices

  • Use for Display: Perfect for showing media previews without needing full details.
  • Cache Responses: If your application queries the same URL repeatedly, store the metadata to avoid unnecessary calls.
  • Upgrade When Needed: If you later need more details, use the full /metadata endpoint.
MetadataImport