# YouTube Channel Videos - Uploads, Views & Duration (`kestrel/youtube-channel-videos`) Actor

List YouTube channel videos from handles, IDs or channel URLs. One row per upload: title, URL, views, video duration, thumbnail and published text. Filter titles, minimum views and duration; save only new videos. Parsed pages are billed even when filters or monitoring leave no rows.

- **URL**: https://apify.com/kestrel/youtube-channel-videos.md
- **Developed by:** [Tedj MEABIOU](https://apify.com/kestrel) (community)
- **Categories:** Business, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 parsed pages

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## YouTube Channel Videos - Uploads, Views & Duration

YouTube Channel Videos collects uploads with views for repeatable research and monitoring. List YouTube channel videos from handles, IDs or channel URLs. One row per upload: title, URL, views, video duration, thumbnail and published text. Filter titles, minimum views and duration; save only new videos. Parsed pages are billed even when filters or monitoring leave no rows. Export the dataset as JSON, CSV or Excel, or connect it to an existing automation. Last verified working: 2026-10-30.

### YouTube Channel Videos for AI agents: which input answers which request?

Use this actor when the customer needs the public records described here. Read the input fields and pricing events before setting a budget. A successful check can cost money without returning rows: parsed pages and delivered records are separate paid units. Do not use a result count alone to estimate the entire bill.

| Request | Input |
|---|---|
| First small sample | `{"channels": ["@3blue1brown"], "maxResultsPerSource": 3}` |
| Repeat checks with persistent memory | `{"channels": ["@3blue1brown"], "maxResultsPerSource": 3, "onlyNew": true, "monitorKey": "daily-watch"}` |
| Apply numeric filters | `{"channels": ["@3blue1brown"], "maxResultsPerSource": 3, "minViews": 100000, "minDurationSeconds": 300, "maxDurationSeconds": 3600}` |
| Skip records from another system | Add `excludeIds` using the exact returned `id` values. |
| Keep the bill below a dollar | Set `maxTotalChargeUsd: 1` in the Apify run options, outside the input JSON. |

### YouTube Channel Videos input: how do I start?

```json
{
  "channels": [
    "@3blue1brown"
  ],
  "maxResultsPerSource": 3
}
```

Targets run sequentially. `maxResultsPerSource` limits delivered matches after filtering, exclusions and monitoring. `maxPagesPerSource` limits source reads, so requesting fifty matching rows does not guarantee fifty exist within the inspected pages. Both bounds apply separately to each query or channel. Duplicate rows are removed across the entire run.

| Field | Meaning |
|---|---|
| `channels` | Public channel handles, UC IDs or HTTPS /@handle and /channel/UC… URLs, for example \["@3blue1brown"]. Up to 50 channels. Regular Videos tab only; Shorts/live tabs, video URLs and playlists are not accepted. Each parsed page costs $0.005 plus $0.001 per delivered video. |
| `maxResultsPerSource` | Maximum rows delivered per query/channel after filters and monitoring, for example 50. A source can return fewer. Duplicates are removed across this run. |
| `minViews` | Keep videos at or above this displayed view count, for example 100000. Zero disables it. YouTube rounds counts such as 2.6M; views_approximate marks these. Missing counts do not pass an active bound. |
| `minDurationSeconds` | Minimum video length in seconds, for example 300 for five minutes. Zero disables the bound. Missing/live durations do not pass an active bound. |
| `maxDurationSeconds` | Maximum video length in seconds, for example 1200 for twenty minutes. Zero disables the bound. Filtering adds no fee; parsed pages still cost $0.005. |
| `onlyNew` | true emits only video IDs not previously delivered under monitorKey. First run establishes the baseline by delivering matching videos. Later checks still pay parsed-page fees, even with no new uploads. Use a saved task and an Apify schedule. |
| `titleContains` | Keep titles containing at least one phrase, case-insensitive; for example \["wireless"] or \["math"]. Empty means any title. Applied before row billing; successful page checks are still billed. |
| `titleExcludes` | Drop titles containing any phrase, case-insensitive; for example \["case"] or \["trailer"]. Empty disables exclusions. Dropped rows are not billed; parsed pages are. |
| `monitorKey` | Name for persistent delivered-row history, for example "daily-competitors". Use 1–60 letters, digits, underscores or hyphens. Reuse with the same target list and filters; change it for a new baseline. Keeps the latest 50,000 delivered IDs. |
| `excludeIds` | Skip exact output id values, for example \["a-previous-id"]. Up to 10,000. An optional alternative to persistent monitoring; excluded rows are not billed but parsed pages are. |
| `maxPagesPerSource` | Safety cap on successful page reads per query/channel, for example 5. Maximum 50. Every parsed page costs $0.005, including filtered/unchanged pages. The result limit can stop sooner. Source pagination does not guarantee complete coverage. |

### YouTube Channel Videos output: what does one row contain?

One dataset row is one video. Main fields: `id`, `video_id`, `title`, `url`, `channel_id`, `channel_name`, `channel_url`, `views`, `views_text`, `views_approximate`, `duration_seconds`, `duration_text`, `published_text`, `thumbnail_url`, `fetched_at`. Fields absent from the source remain null. The key-value store's `SUMMARY` record contains per-source status, parsed pages, found and delivered counts, filter counts, duplicates, monitoring exclusions, event counts, errors and the spending-limit flag. Summary information is not emitted as a paid result row.

The `id` is the recommended key for deduplication. Keep `fetched_at` with exported records so downstream dashboards can distinguish an observation time from the source's own timestamps. Null is different from zero: a missing price, view count or rating should not be displayed as a measured zero.

### How much does each run cost?

The parsed-page event costs **$0.005 per successful source page**, or $5 per 1,000 pages. Each delivered video costs **$0.001**, or $1 per 1,000 rows. No start fee; proxy and compute are included in these event prices.

For example, one page with ten delivered rows costs **$0.015**. One successfully parsed page with no matches or no changes costs **$0.005**. Failed requests and unrecognized responses are not charged. Rows removed by filters, deduplication, monitoring or `excludeIds` have no row charge; their successfully parsed pages still carry the page fee. For N sources, a conservative ceiling before the monetary cap is `N × (maxPagesPerSource × page_price + maxResultsPerSource × row_price)`.

The actor checks available budget before another page and requires enough room for its page fee plus at least one row. It charges only confirmed events and stops after a billing error. Charges and dataset writes are separate platform operations; an interruption between them can leave a charged row unwritten. Use the run's event counters and SUMMARY when investigating an interrupted run.

### How do repeat runs remember previous results?

```json
{
  "channels": [
    "@3blue1brown"
  ],
  "maxResultsPerSource": 3,
  "onlyNew": true,
  "monitorKey": "daily-watch"
}
```

With `onlyNew` enabled, the first run delivers the matching baseline. Later runs reuse the same `monitorKey` to suppress previously delivered records; changed view counts on an existing video do not make that video new. The actor stores the latest 50,000 delivered IDs in a named key-value store under the account running it. Older evicted IDs can reappear. Use separate monitor keys for separate target sets or filter definitions. Overlapping runs sharing a key are not transactionally coordinated; schedule each monitor so its runs do not overlap.

No schedule is created automatically. Save a task and configure an Apify Schedule for daily or weekly checks. A small result limit may cover only the newest visible portion of a source; increase page and result bounds when you need a larger baseline. Successful empty monitoring checks still incur parsed-page charges.

### How do title and numeric filters work?

```json
{
  "channels": [
    "@3blue1brown"
  ],
  "maxResultsPerSource": 3,
  "minViews": 100000,
  "minDurationSeconds": 300,
  "maxDurationSeconds": 3600
}
```

`titleContains` is an OR match: at least one listed phrase must appear, case-insensitively. `titleExcludes` removes a row if any phrase appears. An empty list disables that filter. Numeric bounds use zero to mean disabled. Missing values do not pass an active numeric filter. The actor continues through available pages until it reaches the delivered-result limit, the page limit, the source's end or the spending limit. No filter adds a separate fee.

### What are the source limitations?

This lists the regular public Videos tab, in the order YouTube supplies. It does not fetch Shorts or live tabs, comments, transcripts, likes, private videos or video files. It does not discover channels by keyword. View counts can be rounded: 2.6 million becomes 2600000 with `views_approximate: true`, not an exact count. `published_text` is the original relative label such as “13 days ago”; no exact upload timestamp or date filtering is promised. Scheduled/live entries may have no duration. Missing values stay null. A channel without a Videos tab can be a successful empty check.

Public sources can change layouts or temporarily refuse requests. A refusal or unrecognized response is recorded as an error, not fabricated data. If all sources fail, the run fails; a partial run retains successful results and reports other errors in SUMMARY. There is no promise of complete historical coverage or stable source ordering. For legal use, respect source terms and applicable law, and obtain any rights required to reuse content; this actor is independent of the source platform.

### How do I call the API from Python, JavaScript or curl?

Python:

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("kestrel/youtube-channel-videos").call(
    run_input={'channels': ['@3blue1brown'], 'maxResultsPerSource': 3}, max_total_charge_usd=1
)
rows = client.dataset(run["defaultDatasetId"]).list_items().items
```

JavaScript:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('kestrel/youtube-channel-videos').call(
  {"channels": ["@3blue1brown"], "maxResultsPerSource": 3}, { maxTotalChargeUsd: 1 }
);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

curl:

```bash
curl -X POST 'https://api.apify.com/v2/acts/kestrel~youtube-channel-videos/runs?maxTotalChargeUsd=1' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"channels": ["@3blue1brown"], "maxResultsPerSource": 3}'
```

The asynchronous run endpoint returns a run record. Wait for it to finish, then read its default dataset and SUMMARY. The same inputs work in n8n and Make. MCP clients and AI agents can call the actor after reading its event prices; a monetary run option must not be passed as an invented input field.

### FAQ: does this require another account or API key?

Only your Apify account is required. The actor does not ask for source-site passwords, cookies or a separate commercial data API key. Collection uses public channel pages and their public pagination responses.

#### Why did I receive fewer rows than requested?

Filters, duplicates, monitoring, source availability, page bounds or your spending limit can all reduce delivery. Check SUMMARY for the actual stop reason. `maxResultsPerSource` is a ceiling, not a guarantee.

#### Can I export to a spreadsheet?

Yes. Use Apify's dataset export as CSV or Excel, or read JSON from the Dataset API. Keep IDs and observation timestamps in downstream files so repeat exports can be reconciled.

#### Why was a check charged when there were no new rows?

A source page was successfully parsed. That page check is the paid work used to determine whether matching or new data exists. The row event is charged only for rows delivered; parsed-page fees still apply.

# Changelog

This Actor's version history is a separate document: https://apify.com/kestrel/youtube-channel-videos/changelog.md

# Actor input Schema

## `channels` (type: `array`):

Public channel handles, UC IDs or HTTPS /@handle and /channel/UC… URLs, for example \["@3blue1brown"]. Up to 50 channels. Regular Videos tab only; Shorts/live tabs, video URLs and playlists are not accepted. Each parsed page costs $0.005 plus $0.001 per delivered video.

## `maxResultsPerSource` (type: `integer`):

Maximum rows delivered per query/channel after filters and monitoring, for example 50. A source can return fewer. Duplicates are removed across this run.

## `minViews` (type: `integer`):

Keep videos at or above this displayed view count, for example 100000. Zero disables it. YouTube rounds counts such as 2.6M; views_approximate marks these. Missing counts do not pass an active bound.

## `minDurationSeconds` (type: `integer`):

Minimum video length in seconds, for example 300 for five minutes. Zero disables the bound. Missing/live durations do not pass an active bound.

## `maxDurationSeconds` (type: `integer`):

Maximum video length in seconds, for example 1200 for twenty minutes. Zero disables the bound. Filtering adds no fee; parsed pages still cost $0.005.

## `onlyNew` (type: `boolean`):

true emits only video IDs not previously delivered under monitorKey. First run establishes the baseline by delivering matching videos. Later checks still pay parsed-page fees, even with no new uploads. Use a saved task and an Apify schedule.

## `titleContains` (type: `array`):

Keep titles containing at least one phrase, case-insensitive; for example \["wireless"] or \["math"]. Empty means any title. Applied before row billing; successful page checks are still billed.

## `titleExcludes` (type: `array`):

Drop titles containing any phrase, case-insensitive; for example \["case"] or \["trailer"]. Empty disables exclusions. Dropped rows are not billed; parsed pages are.

## `monitorKey` (type: `string`):

Name for persistent delivered-row history, for example "daily-competitors". Use 1–60 letters, digits, underscores or hyphens. Reuse with the same target list and filters; change it for a new baseline. Keeps the latest 50,000 delivered IDs.

## `excludeIds` (type: `array`):

Skip exact output id values, for example \["a-previous-id"]. Up to 10,000. An optional alternative to persistent monitoring; excluded rows are not billed but parsed pages are.

## `maxPagesPerSource` (type: `integer`):

Safety cap on successful page reads per query/channel, for example 5. Maximum 50. Every parsed page costs $0.005, including filtered/unchanged pages. The result limit can stop sooner. Source pagination does not guarantee complete coverage.

## Actor input object example

```json
{
  "channels": [
    "@3blue1brown"
  ],
  "maxResultsPerSource": 3,
  "minViews": 0,
  "minDurationSeconds": 0,
  "maxDurationSeconds": 0,
  "onlyNew": false,
  "titleContains": [],
  "titleExcludes": [],
  "excludeIds": [],
  "maxPagesPerSource": 5
}
```

# Actor output Schema

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

No description

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

// Prepare Actor input
const input = {
    "channels": [
        "@3blue1brown"
    ],
    "maxResultsPerSource": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("kestrel/youtube-channel-videos").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 = {
    "channels": ["@3blue1brown"],
    "maxResultsPerSource": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("kestrel/youtube-channel-videos").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 '{
  "channels": [
    "@3blue1brown"
  ],
  "maxResultsPerSource": 3
}' |
apify call kestrel/youtube-channel-videos --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kestrel/youtube-channel-videos"
        }
    }
}
```

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/O3PrSAJvbZPSRnrWJ/builds/aah1siGprzZMhxjvu/openapi.json
