# VideoIntel - Universal Video Metadata Extractor (`upworkprashantp/videointel-video-metadata-extractor`) Actor Check video URL support and extract metadata, thumbnails, metrics, formats and permitted downloads from YouTube, TikTok, Instagram, Facebook, X/Twitter, Vimeo, Twitch, Kick, SoundCloud and 1,500+ sites. - **URL**: https://apify.com/upworkprashantp/videointel-video-metadata-extractor.md - **Developed by:** [Prashant Patil](https://apify.com/upworkprashantp) (community) - **Categories:** Videos, Social media, Developer tools - **Stats:** 3 total users, 1 monthly users, 90.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.00005 / actor start This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## VideoIntel - Universal Video Metadata Extractor Extract structured metadata from public video URLs and return clean Apify Dataset rows. VideoIntel is built for bulk video intelligence workflows such as creator research, social media monitoring, video cataloging, lead enrichment, content audits, and internal media operations. > Important: Use this Actor only for videos you are legally allowed to access and process. Do not use it to bypass DRM, paywalls, private content protections, or a platform's access controls. ### What You Get - Bulk metadata extraction from public video URLs. - Support for many `yt-dlp` compatible platforms, including YouTube videos, YouTube Shorts, TikTok videos, Instagram Reels, Facebook videos, Vimeo, Dailymotion, and more. - Structured JSON output with title, uploader, duration, views, likes, comments, upload date, thumbnails, source URL, platform IDs, and channel details. - Optional format metadata for users who need technical video details. - Failed or unsupported URLs returned as dataset rows, so one bad URL does not stop a bulk run. - Optional download mode for videos you are legally allowed to download. ### Common Use Cases - Build creator and channel research datasets. - Audit public video catalogs at scale. - Enrich lead lists with video engagement metrics. - Monitor public social video performance. - Collect thumbnail, title, duration, and upload metadata for internal media tools. ### Input ```json { "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "urlsDatasetId": "", "datasetUrlField": "url", "datasetStartOffset": 0, "operation": "metadata", "includeFormats": false, "includeDirectMediaUrls": false, "includeSubtitles": false, "proxyConfiguration": { "useApifyProxy": true }, "maxConcurrency": 3, "maxUrls": 0, "maxRetries": 2, "timeoutSecs": 60, "maxFileSizeMb": 100, "failOnUnsupported": false } ```` ### Large Batches The direct **Video URLs** input is meant for quick runs and API examples. For large jobs such as 10,000 or 100,000 URLs, put the URLs in an Apify Dataset and select it in **Input Dataset**. Expected Dataset row shape: ```json { "url": "https://www.youtube.com/watch?v=..." } ``` You can also use `sourceUrl`, `videoUrl`, or `webpageUrl`, or set **Dataset URL field** to your own column name. For very large runs: - Use **Input Dataset** instead of pasting all URLs into the Actor input. - Keep `maxConcurrency` modest for strict platforms, usually `1` to `3`. - Use **Dataset start offset** to resume or split a huge list into chunks. - Use **Max URLs to process** to test a small slice before launching the full batch. - Give the run enough timeout, memory, proxy access, and maximum cost allowance for the expected number of results. Internally, VideoIntel streams URLs through a bounded worker queue, so it does not create one task per input URL. ### Proxy Support Some platforms treat cloud traffic differently from local browser traffic. If a URL works on your laptop but fails in an Apify cloud run, enable proxies in the **Proxy configuration** input. When proxying is enabled, VideoIntel creates a separate proxy session for each input URL. This gives each video extraction a stable IP during its own `yt-dlp` requests while still rotating between URLs in bulk runs. Recommended setup for strict platforms: - Enable Apify Proxy in **Proxy configuration**. - Use residential proxies when available for YouTube, TikTok, Instagram, Facebook, and other platforms that aggressively block datacenter IPs. - Keep `maxConcurrency` modest for strict platforms, usually `1` to `3`. - Keep `maxRetries` enabled so temporary proxy challenges can retry with a fresh proxy session. - Retry failed URLs in a later run if the platform temporarily rate-limits or challenges the proxy IP. Proxy availability and cost depend on the Apify account and selected proxy group. Proxies reduce IP-based blocking, but they cannot access private, deleted, region-blocked, age-restricted, paywalled, or account-only content. YouTube can still challenge datacenter or automatic proxy IPs. For YouTube-heavy batches, use residential proxies when available. ### Output Each URL creates one Dataset item: ```json { "sourceUrl": "https://www.youtube.com/watch?v=...", "status": "success", "platform": "Youtube", "videoId": "...", "title": "Video title", "duration": 123, "viewCount": 100000, "likeCount": 5000, "commentCount": 200, "uploader": "Channel name", "uploadDate": "2026-06-15", "thumbnail": "https://...", "webpageUrl": "https://..." } ``` Failed URLs are returned as rows instead of crashing the run, unless `failOnUnsupported` is true. ```json { "sourceUrl": "https://example.com/not-supported", "status": "failed", "errorCode": "download-error", "errorMessage": "Unsupported URL" } ``` ### Download Mode Set `operation` to `download`. ```json { "urls": ["https://www.youtube.com/watch?v=..."], "operation": "download", "preferredQuality": "480p", "maxFileSizeMb": 100 } ``` Downloaded files are stored in the run's default key-value store. Dataset rows include: ```json { "status": "success", "fileKey": "VIDEO-abc123.mp4", "fileUrl": "https://api.apify.com/v2/key-value-stores//records/VIDEO-abc123.mp4" } ``` Users need their Apify token to access private run storage through the API. Only use download mode for videos you own, control, or are otherwise legally allowed to download. This Actor does not bypass DRM, paywalls, private content protections, or platform access controls. ### Pricing This Actor uses pay-per-event pricing. Each metadata result is written as one default dataset item, so pricing is predictable for both small and bulk jobs. You pay for: - Actor start. - Each video metadata result written to the default dataset. Download mode may involve additional file storage and transfer costs depending on the run configuration. ### API usage Synchronous call, best for small runs under 5 minutes: ```bash curl -X POST \ "https://api.apify.com/v2/acts/upworkprashantp~videointel-video-metadata-extractor/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "operation": "metadata" }' ``` Asynchronous call, best for bulk jobs: ```bash curl -X POST \ "https://api.apify.com/v2/acts/upworkprashantp~videointel-video-metadata-extractor/runs?token=YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "operation": "metadata" }' ``` Then use the returned `defaultDatasetId` to fetch results: ```bash curl "https://api.apify.com/v2/datasets/DEFAULT_DATASET_ID/items?token=YOUR_APIFY_TOKEN&format=json" ``` # Actor input Schema ## `urls` (type: `array`): One or more video URLs for quick runs. For very large batches, use the Input Dataset field instead of pasting thousands of URLs here. ## `urlsDatasetId` (type: `string`): Optional. Select an Apify Dataset containing URL rows for large runs such as 10,000 or 100,000 videos. Each row should contain a URL field. ## `datasetUrlField` (type: `string`): Field name in the input Dataset that contains the video URL. If missing, the Actor also tries url, sourceUrl, videoUrl, and webpageUrl. ## `datasetStartOffset` (type: `integer`): Start reading the input Dataset from this row offset. Useful for splitting or resuming very large jobs. ## `operation` (type: `string`): Use metadata for fast structured data extraction. Use download only for videos you have rights/permission to download. ## `preferredQuality` (type: `string`): Used only when operation is download. ## `includeFormats` (type: `boolean`): When true, returns selected available format metadata. Keep false for cheaper/faster bulk runs. ## `includeDirectMediaUrls` (type: `boolean`): When true, includes temporary direct media URLs in formats. These URLs can expire and may be very large. Disabled by default. ## `includeSubtitles` (type: `boolean`): Includes subtitle and automatic caption language metadata when available. Does not download subtitle files. ## `proxyConfiguration` (type: `object`): Use Apify Proxy or custom proxies for cloud runs. Rotating proxies are recommended for YouTube, TikTok, Instagram, Facebook, and other platforms that block datacenter traffic. Residential proxies usually work better for strict platforms but may cost more. ## `maxConcurrency` (type: `integer`): Number of URLs processed in parallel. Keep low for download mode. ## `maxUrls` (type: `integer`): Optional safety limit across direct URLs and Dataset URLs. Use 0 to process all available input URLs. ## `maxRetries` (type: `integer`): Retries metadata extraction with a fresh proxy session for transient proxy or YouTube bot-check failures. Download mode does not retry to avoid duplicate traffic and charges. ## `timeoutSecs` (type: `integer`): Network timeout passed to yt-dlp. ## `maxFileSizeMb` (type: `integer`): Download mode guardrail. Files larger than this are skipped after detection to control storage/traffic costs. ## `failOnUnsupported` (type: `boolean`): When false, unsupported/error URLs are returned as dataset rows instead of failing the whole run. ## Actor input object example ```json { "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "datasetUrlField": "url", "datasetStartOffset": 0, "operation": "metadata", "preferredQuality": "480p", "includeFormats": false, "includeDirectMediaUrls": false, "includeSubtitles": false, "proxyConfiguration": { "useApifyProxy": true }, "maxConcurrency": 3, "maxUrls": 0, "maxRetries": 2, "timeoutSecs": 60, "maxFileSizeMb": 100, "failOnUnsupported": false } ``` # Actor output Schema ## `results` (type: `string`): No description ## `summary` (type: `string`): No description ## `files` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("upworkprashantp/videointel-video-metadata-extractor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("upworkprashantp/videointel-video-metadata-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "proxyConfiguration": { "useApifyProxy": true } }' | apify call upworkprashantp/videointel-video-metadata-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=upworkprashantp/videointel-video-metadata-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "VideoIntel - Universal Video Metadata Extractor", "description": "Check video URL support and extract metadata, thumbnails, metrics, formats and permitted downloads from YouTube, TikTok, Instagram, Facebook, X/Twitter, Vimeo, Twitch, Kick, SoundCloud and 1,500+ sites.", "version": "0.1", "x-build-id": "zBLDMofGUbmFVG4og" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/upworkprashantp~videointel-video-metadata-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-upworkprashantp-videointel-video-metadata-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/upworkprashantp~videointel-video-metadata-extractor/runs": { "post": { "operationId": "runs-sync-upworkprashantp-videointel-video-metadata-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/upworkprashantp~videointel-video-metadata-extractor/run-sync": { "post": { "operationId": "run-sync-upworkprashantp-videointel-video-metadata-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "urls": { "title": "Video URLs", "minItems": 1, "maxItems": 1000, "type": "array", "description": "One or more video URLs for quick runs. For very large batches, use the Input Dataset field instead of pasting thousands of URLs here.", "items": { "type": "string" } }, "urlsDatasetId": { "title": "Input Dataset", "type": "string", "description": "Optional. Select an Apify Dataset containing URL rows for large runs such as 10,000 or 100,000 videos. Each row should contain a URL field." }, "datasetUrlField": { "title": "Dataset URL field", "type": "string", "description": "Field name in the input Dataset that contains the video URL. If missing, the Actor also tries url, sourceUrl, videoUrl, and webpageUrl.", "default": "url" }, "datasetStartOffset": { "title": "Dataset start offset", "minimum": 0, "type": "integer", "description": "Start reading the input Dataset from this row offset. Useful for splitting or resuming very large jobs.", "default": 0 }, "operation": { "title": "Operation", "enum": [ "metadata", "download" ], "type": "string", "description": "Use metadata for fast structured data extraction. Use download only for videos you have rights/permission to download.", "default": "metadata" }, "preferredQuality": { "title": "Preferred download quality", "enum": [ "360p", "480p", "720p", "best" ], "type": "string", "description": "Used only when operation is download.", "default": "480p" }, "includeFormats": { "title": "Include available formats", "type": "boolean", "description": "When true, returns selected available format metadata. Keep false for cheaper/faster bulk runs.", "default": false }, "includeDirectMediaUrls": { "title": "Include direct media URLs", "type": "boolean", "description": "When true, includes temporary direct media URLs in formats. These URLs can expire and may be very large. Disabled by default.", "default": false }, "includeSubtitles": { "title": "Include subtitle metadata", "type": "boolean", "description": "Includes subtitle and automatic caption language metadata when available. Does not download subtitle files.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Use Apify Proxy or custom proxies for cloud runs. Rotating proxies are recommended for YouTube, TikTok, Instagram, Facebook, and other platforms that block datacenter traffic. Residential proxies usually work better for strict platforms but may cost more.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of URLs processed in parallel. Keep low for download mode.", "default": 3 }, "maxUrls": { "title": "Max URLs to process", "minimum": 0, "type": "integer", "description": "Optional safety limit across direct URLs and Dataset URLs. Use 0 to process all available input URLs.", "default": 0 }, "maxRetries": { "title": "Max retries per URL", "minimum": 0, "maximum": 5, "type": "integer", "description": "Retries metadata extraction with a fresh proxy session for transient proxy or YouTube bot-check failures. Download mode does not retry to avoid duplicate traffic and charges.", "default": 2 }, "timeoutSecs": { "title": "Timeout per URL in seconds", "minimum": 10, "maximum": 300, "type": "integer", "description": "Network timeout passed to yt-dlp.", "default": 60 }, "maxFileSizeMb": { "title": "Max file size MB", "minimum": 1, "maximum": 2048, "type": "integer", "description": "Download mode guardrail. Files larger than this are skipped after detection to control storage/traffic costs.", "default": 100 }, "failOnUnsupported": { "title": "Fail run on unsupported URLs", "type": "boolean", "description": "When false, unsupported/error URLs are returned as dataset rows instead of failing the whole run.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```