YouTube Regional Video Availability Checker

Check supplied public YouTube videos across selected countries and export one typed availability row per video-country pair.

YouTube Regional Video Availability Checker turns URLs and video IDs into a reusable YouTube availability dataset for rights audits, campaign launch checks, localization planning, and recurring distribution monitoring. It uses public YouTube player metadata, needs no YouTube API key or login, and never downloads video media.

What does YouTube Regional Video Availability Checker do?

The Actor accepts up to 100 public YouTube videos and up to 50 ISO country codes per run.

For each unique video it:

1. resolves watch, Shorts, live, embed, and youtu.be URLs to a canonical video ID;
2. reads the public allowed-country metadata exposed by YouTube;
3. compares every selected country with that list;
4. exports one record per video and country;
5. includes video identity, channel identity, classification, and check time.

A run with 3 videos and 5 countries produces 15 dataset rows and charges 15 country-result events.

Who is it for?

Rights and distribution teams

Audit whether licensed video assets appear available in every contracted territory.

Campaign managers

Check launch videos before activating regional ads or landing pages.

Localization teams

Find markets that may require a localized replacement video.

Agencies and creator operations teams

Export a repeatable evidence table for client reporting instead of maintaining manual screenshots.

Data and QA teams

Schedule the same input and compare country-level records across runs in a spreadsheet, warehouse, or monitoring workflow.

Why use this Actor?

• Batch URLs and raw IDs in one run.
• Select only the countries relevant to a campaign or rights agreement.
• Receive one flat row per video-country pair for easy CSV and SQL analysis.
• Keep canonical video, channel, and timestamp fields beside every result.
• Distinguish restricted from unknown instead of inventing an answer when metadata is missing.
• Use direct public metadata first and a bounded residential HTTP fallback for reliability.
• Avoid browser rendering and media downloads in normal runs.
• Run without YouTube login, cookies, or a YouTube Data API key.

What data is extracted?

Field	Type	Description
videoId	string	Canonical 11-character YouTube video ID
videoUrl	string	Canonical public watch URL
title	string or null	Public video title
channelName	string or null	Public channel display name
channelId	string or null	YouTube channel ID
thumbnailUrl	string or null	Best public thumbnail URL returned in metadata
countryCode	string	Requested ISO alpha-2 country code
availabilityStatus	string	available, restricted, or unknown
isAvailable	boolean or null	Country availability; null means metadata was unavailable
restrictionClassification	string	Evidence used for the classification
allowedCountryCount	number or null	Size of YouTube's exposed allowed-country list
checkedAt	string	ISO 8601 check timestamp

How availability is classified

available means the selected country appears in YouTube's public allowed-country list.

restricted means YouTube exposed an allowed-country list and the selected country does not appear in it.

unknown means YouTube did not expose enough public regional metadata to classify that video safely. Unknown is not the same as restricted.

The restrictionClassification field makes this distinction explicit:

• allowed_country_list
• not_in_allowed_country_list
• metadata_unavailable

How much does it cost to check YouTube video availability?

Pricing is pay per event:

• $0.0135 once when a run starts;
• one country-result event for each saved video-country row;
• $0.0008 per country result at the BRONZE tier.

Workload	Charged country results
1 video × 6 countries	6
10 videos × 10 countries	100
100 videos × 20 countries	2,000

Total BRONZE price is the run-start fee plus the number of saved country results multiplied by the active country-result price. Your account tier may use a different per-result event price. Residential proxy and compute usage are covered by event billing.

How to get started

1. Open the Actor input page.
2. Add one or more public YouTube URLs or video IDs.
3. Enter the ISO country codes you need to audit.
4. Keep the default concurrency unless you have a large batch.
5. Click Start.
6. Open the Regional availability dataset view.
7. Export JSON, CSV, Excel, XML, or connect through the API.

Input parameters

videoUrlsOrIds

Required array with 1–100 values.

Supported examples:

• https://www.youtube.com/watch?v=dQw4w9WgXcQ
• https://youtu.be/dQw4w9WgXcQ
• https://www.youtube.com/shorts/dQw4w9WgXcQ
• https://www.youtube.com/live/dQw4w9WgXcQ
• dQw4w9WgXcQ

Duplicates are removed before checking and charging.

countries

Required array with 1–50 ISO 3166-1 alpha-2 codes.

Examples: US, GB, DE, FR, JP, BR, AU, IN.

Codes are normalized to uppercase. Invalid values fail the run instead of silently producing misleading output.

maxConcurrency

Optional integer from 1 to 8. The default is 3.

Higher concurrency can shorten large runs, but the default is the recommended stable setting.

Example input

{
  "videoUrlsOrIds": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "kJQP7kiw5Fk"
  ],
  "countries": ["US", "GB", "DE", "FR", "JP"],
  "maxConcurrency": 2
}

This checks two unique videos, produces ten country rows, and charges ten country-result events.

Example output

{
  "videoId": "dQw4w9WgXcQ",
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "channelName": "Rick Astley",
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "thumbnailUrl": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/maxresdefault.webp",
  "countryCode": "US",
  "availabilityStatus": "available",
  "isAvailable": true,
  "restrictionClassification": "allowed_country_list",
  "allowedCountryCount": 249,
  "checkedAt": "2026-08-29T20:08:44.730Z"
}

A video that does not expose regional metadata still gets one row per requested country, with availabilityStatus: "unknown", isAvailable: null, and restrictionClassification: "metadata_unavailable".

Campaign launch workflow

Create a task containing every approved campaign video and the exact paid-media markets.

Run it before launch, export CSV, and filter rows where availabilityStatus is not available. Schedule the task during the campaign to detect changes in the source metadata.

Rights territory audit workflow

Use one video list per rights package and enter the contracted territories as country codes.

Store each run's checkedAt records in your warehouse. Compare status by videoId + countryCode to identify newly restricted or newly available markets.

Spreadsheet and database integration

The flat output works well with:

• Google Sheets and Microsoft Excel;
• Airtable and Notion databases;
• BigQuery, Snowflake, and PostgreSQL;
• Make, Zapier, and n8n;
• campaign QA and content operations dashboards.

Use videoId and countryCode as the logical comparison key. Use checkedAt as the observation timestamp.

Use the API with JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor(
  'automation-lab/youtube-regional-video-availability-checker'
).call({
  videoUrlsOrIds: ['dQw4w9WgXcQ', 'kJQP7kiw5Fk'],
  countries: ['US', 'GB', 'DE', 'FR'],
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Use the API with Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor(
    'automation-lab/youtube-regional-video-availability-checker'
).call(run_input={
    'videoUrlsOrIds': ['dQw4w9WgXcQ', 'kJQP7kiw5Fk'],
    'countries': ['US', 'GB', 'DE', 'FR'],
})

items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

Use the API with cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~youtube-regional-video-availability-checker/runs?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "videoUrlsOrIds": ["dQw4w9WgXcQ", "kJQP7kiw5Fk"],
    "countries": ["US", "GB", "DE", "FR"]
  }'

Fetch the completed run's dataset through its defaultDatasetId.

Use with Apify MCP

Claude Code setup:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/youtube-regional-video-availability-checker"

Claude Desktop setup

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/youtube-regional-video-availability-checker"
    }
  }
}

Cursor setup

Use the same mcpServers.apify.url value in Cursor's MCP settings.

VS Code setup

Use the same mcpServers.apify.url value in VS Code's MCP server settings.

Example prompts:

• "Check these public YouTube videos in US, GB, DE, FR, JP, and BR."
• "Export a country-by-country availability table for this campaign video list."
• "Show only unknown or restricted rows from my latest regional rights audit."

Reliability and retries

The Actor first tries lightweight direct public metadata.

When YouTube does not expose useful regional data on that route, it uses up to two fresh US residential HTTP sessions. It does not load video, audio, images, fonts, or a full browser page in normal operation.

If all bounded attempts lack country metadata, the Actor emits truthful unknown rows. It does not guess that the video is blocked.

Limits and expected behavior

• Public videos only.
• Maximum 100 supplied videos per run.
• Maximum 50 countries per run.
• Private, deleted, login-only, age-gated, or members-only videos may return unknown metadata.
• YouTube may change its public player response.
• Results represent public metadata observed at checkedAt, not a guarantee of future playback.
• Account, subscription, device, age, and network policy can affect an individual viewer beyond regional metadata.

Troubleshooting

Why is a result unknown?

YouTube did not expose a usable allowed-country list after the bounded direct and residential attempts. Retry later and confirm that the source video is public.

Why did my run fail immediately?

Check that every video value is a supported YouTube URL or an 11-character ID and every country is a two-letter ISO code. Input validation fails closed on malformed values.

Why are there more dataset rows than video checks?

The dataset has one row for every video-country pair, and each saved row is one country-result event.

Does this download or play the videos?

No. It reads public player metadata and does not download the media stream.

Responsible use and legality

Use the Actor only for public videos and legitimate rights, campaign, localization, research, or operational workflows.

You are responsible for following YouTube's terms, applicable copyright rules, privacy law, contractual rights, and local regulations. The Actor does not bypass authentication, private videos, subscriptions, DRM, or access controls.

Do not treat a regional metadata result as legal advice or proof of ownership.

Related automation-lab Actors

• YouTube Channel Videos Scraper — collect a public channel's video catalog before checking selected assets.
• YouTube Trending Videos Scraper — discover trending public videos for market research.
• YouTube Thumbnail Downloader — export public thumbnail assets and metadata.

FAQ

Do I need a YouTube API key?

No. The Actor reads public player metadata.

Do I need a YouTube account or cookies?

No. The production route is logged out.

Can I check Shorts and live URLs?

Yes, when the URL contains a normal 11-character video ID and the video exposes public metadata.

Can I check all countries?

You can supply up to 50 countries in one run. Split a larger global audit into multiple tasks if needed.

Can I schedule recurring checks?

Yes. Save the input as an Apify task and attach a daily, weekly, or campaign-specific schedule.

Are restricted countries inferred safely?

A country is marked restricted only when YouTube exposes an allowed-country list and that country is absent. Missing metadata produces unknown, not restricted.

How should I detect changes?

Compare consecutive records by videoId and countryCode, then inspect changes in availabilityStatus and checkedAt.

Does the number of countries change the charge?

Yes. Each saved video-country row is one country-result event, so selecting more countries produces and charges more results.