# YouTube Regional Video Availability Checker (`automation-lab/youtube-regional-video-availability-checker`) Actor

Check public YouTube videos across selected countries and export one regional availability record per video and country for rights and campaign monitoring.

- **URL**: https://apify.com/automation-lab/youtube-regional-video-availability-checker.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.48 / 1,000 country-result extracteds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## 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

```json
{
  "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

```json
{
  "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

```js
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

```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

```bash
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:

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

#### Claude Desktop setup

```json
{
  "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](https://apify.com/automation-lab/youtube-channel-videos-scraper) — collect a public channel's video catalog before checking selected assets.
- [YouTube Trending Videos Scraper](https://apify.com/automation-lab/youtube-trending-videos-scraper) — discover trending public videos for market research.
- [YouTube Thumbnail Downloader](https://apify.com/automation-lab/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.

# Actor input Schema

## `videoUrlsOrIds` (type: `array`):

Public YouTube watch, Shorts, live, embed, or youtu.be URLs, or 11-character video IDs. Duplicates are removed.

## `countries` (type: `array`):

ISO 3166-1 alpha-2 country codes, such as US, GB, DE, FR, JP, or BR. One output row is produced for each video-country pair.

## `maxConcurrency` (type: `integer`):

Number of videos checked concurrently. Keep the default for stable recurring audits.

## Actor input object example

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

# Actor output Schema

## `dataset` (type: `string`):

Typed video-country availability rows in the default dataset.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "videoUrlsOrIds": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ],
    "countries": [
        "US",
        "GB",
        "DE",
        "FR"
    ],
    "maxConcurrency": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/youtube-regional-video-availability-checker").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "videoUrlsOrIds": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
    "countries": [
        "US",
        "GB",
        "DE",
        "FR",
    ],
    "maxConcurrency": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/youtube-regional-video-availability-checker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "videoUrlsOrIds": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "countries": [
    "US",
    "GB",
    "DE",
    "FR"
  ],
  "maxConcurrency": 3
}' |
apify call automation-lab/youtube-regional-video-availability-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/youtube-regional-video-availability-checker"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/m3bAKRJo17JEvmege/builds/yeEllQHOgmCtuTyMD/openapi.json