# YouTube Channel Lookup – Stats, Upload Cadence & Videos (`coregent/youtube-channel-lookup`) Actor

Give an AI agent a YouTube channel and get back, in seconds, its size, how often it uploads, how its recent videos perform and the newest videos with links, in one record. One channel per call. No login, no API keys.

- **URL**: https://apify.com/coregent/youtube-channel-lookup.md
- **Developed by:** [Delowar Munna](https://apify.com/coregent) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 channel lookups

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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?

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 Lookup – Stats, Upload Cadence & Videos (API for AI agents)

![YouTube Channel Lookup](https://raw.githubusercontent.com/coregentdevspace/youtube-channel-lookup-assets/main/thumbnail-youtube-channel-lookup.png)

**Is this creator still active, and what do their videos get?** Give this Actor one YouTube channel and get back, in
seconds, its size, how often it uploads, how its recent videos perform and the newest videos with links, in one
record.

Built as a **tool for AI agents** (Claude, ChatGPT, Cursor, n8n or your own) through Apify's MCP server, and for
developers calling the Apify API from creator-vetting and prospecting pipelines. One channel per call, a compact
response, and a predictable price per lookup. No login, no cookies, no API keys.

### ✨ What you get

- **Channel stats:** title, handle, description, subscribers, total views, video count, country, joined date,
  verified badge and the links on the channel page.
- **A recent-activity summary:** uploads in the last 30 and 90 days, days since the last upload, average days between
  uploads, and the median and average views of recent videos.
- **The newest videos**, up to 60: title, link, estimated publish date (plus the date text as YouTube shows it),
  views and duration. Or list the channel's Shorts instead.
- **Any way you know the channel:** `@handle`, channel URL (`/@handle`, `/channel/UC…`, `/c/…`, `/user/…`), channel
  ID, or a plain name.

### 🧑‍💼 Who it's for

- **Influencer-marketing and sponsorship agents:** "Is this creator worth sponsoring? Are they still uploading? What
  does a typical video get?" as one tool call.
- **Competitor and market research:** how often a brand's channel posts and how it performs.
- **Sales prospecting:** qualify creators and brands before outreach.
- **Developers:** one API call per channel to enrich a creator list.

### 🤖 Use it from an AI agent (MCP)

Connect Apify's MCP server with just this Actor as a tool, using this URL:

```
https://mcp.apify.com?tools=coregent/youtube-channel-lookup
```

- **Claude (claude.ai or Claude Desktop):** Settings → Connectors → **Add custom connector**, paste the URL, and sign
  in with Apify when asked.
- **Claude Code:**
  `claude mcp add youtube-channel-lookup "https://mcp.apify.com?tools=coregent/youtube-channel-lookup" -t http`
- **ChatGPT:** add a custom MCP server with the same URL and choose OAuth.
- **Cursor, VS Code and other clients that take a remote URL:**

```json
{ "mcpServers": { "youtube-channel-lookup": { "url": "https://mcp.apify.com?tools=coregent/youtube-channel-lookup" } } }
```

Sign-in uses your own Apify account (the free plan works), and runs are billed there. The agent sees one tool,
`coregent--youtube-channel-lookup`, with four inputs, plus Apify's helpers for reading run results. Already using
Apify's MCP server with other Actors? Add `coregent/youtube-channel-lookup` to your `tools=` list, comma-separated.

**Try asking your agent:**

- "How often does @mkbhd upload, and what does a typical recent video get?"
- "Is this creator still active? Check @veritasium and tell me the days since the last upload."
- "Compare upload cadence and median views for @LinusTechTips and @mkbhd over the last 90 days."
- "We're considering sponsoring @aliabdaal. Summarise the channel's size and recent performance."

A typical tool call:

```json
{ "channel": "@mkbhd", "maxVideos": 5 }
```

The agent gets back one JSON object (below), small enough to reason over directly. Set `"maxVideos": 0` for the
channel and activity summary only, the cheapest call.

If a plain name matches several channels (say, "Tesla"), the call returns `status: "ambiguous"` with up to 5
`candidates`, free of charge, and the agent calls again with the right handle or channel ID.

### 🚀 Use it from the API

Run it synchronously and read the result in one request:

```bash
curl -X POST "https://api.apify.com/v2/acts/coregent~youtube-channel-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"channel": "@veritasium", "maxVideos": 10}'
```

The same object is also saved to the run's `OUTPUT` record.

### 📥 Input

| Field | Description |
|---|---|
| `channel` (required) | `@handle`, channel URL, channel ID (`UC…`) or name, e.g. `@mkbhd`. |
| `maxVideos` | 0–60, default 10. `0` returns the channel and activity summary only. |
| `videoType` | `long` (regular uploads, default) or `shorts`. The activity summary always uses regular uploads. |
| `sinceDays` | Window for the activity summary and the regular-upload list, 7–365, default 90. |

#### Example inputs

A channel's stats, activity and its 20 newest videos from the last 180 days (the run behind the sample output and
screenshots below):

```json
{ "channel": "@mkbhd", "maxVideos": 20, "videoType": "long", "sinceDays": 180 }
```

A channel's stats, activity and its newest videos from the last 90 days:

```json
{ "channel": "@MrBeast", "maxVideos": 10 }
```

Summary only, by channel ID:

```json
{ "channel": "UCBJycsmduvYEL83R_U4JriQ", "maxVideos": 0 }
```

By name, last 30 days:

```json
{ "channel": "Apple", "maxVideos": 5, "sinceDays": 30 }
```

The channel's Shorts:

```json
{ "channel": "https://www.youtube.com/@mkbhd", "videoType": "shorts", "maxVideos": 10 }
```

### 📦 Output

One record per call. This is the real record from `{ "channel": "@mkbhd", "maxVideos": 20, "sinceDays": 180 }`, with
the description, links and videos trimmed here:

```json
{
  "status": "ok",
  "query": "@mkbhd",
  "checkedAt": "2026-11-19T11:14:26.104Z",
  "resolvedBy": "handle",
  "channel": {
    "channelId": "UCBJycsmduvYEL83R_U4JriQ",
    "handle": "@mkbhd",
    "title": "Marques Brownlee",
    "url": "https://www.youtube.com/@mkbhd",
    "description": "MKBHD: Quality Tech Videos | YouTuber | Geek | Consumer Electronics | Tech Head | Internet Personality! ...",
    "country": "United States",
    "joinedDate": "2008-03-21",
    "subscribers": 21400000,
    "subscribersHidden": false,
    "totalViews": 5907552880,
    "videoCount": 1800,
    "verified": true,
    "links": [
      { "title": "Twitter", "url": "https://twitter.com/MKBHD" },
      { "title": "Instagram", "url": "https://instagram.com/MKBHD" },
      { "title": "Reddit", "url": "https://reddit.com/r/MKBHD" }
    ]
  },
  "activity": {
    "windowDays": 180,
    "uploadsLast30Days": 6,
    "uploadsLast90Days": 20,
    "uploadsInWindow": 33,
    "daysSinceLastUpload": 1,
    "avgDaysBetweenUploads": 4.7,
    "recentMedianViews": 6300000,
    "recentAvgViews": 7533333
  },
  "videos": [
    {
      "videoId": "KTDJiVpSDTI",
      "url": "https://www.youtube.com/watch?v=KTDJiVpSDTI",
      "title": "Can You Trust MKBHD?",
      "publishedAt": "2026-11-18",
      "publishedText": "1 day ago",
      "isShort": false,
      "durationSeconds": 859,
      "views": 3000000,
      "isLive": false
    }
  ],
  "candidates": [],
  "truncated": true,
  "notes": [
    "subscribers, videoCount and per-video views are rounded as YouTube displays them (e.g. 21.4M); totalViews is exact.",
    "Upload dates are estimated from YouTube's relative text (\"3 months ago\"); counts beyond about 30 days work in month steps and are approximate."
  ]
}
```

`truncated: true` means the channel had more videos in the window (33) than `maxVideos` returned (20).

#### Channel summary

The stats and activity in one row:

![Channel summary tab](https://raw.githubusercontent.com/coregentdevspace/youtube-channel-lookup-assets/main/youtube-channel-lookup-output-overview-table-view.png)

#### Videos

One row per video returned. A row from the same run:

```json
{
  "query": "@mkbhd",
  "videoId": "hdMszZ2ah5Q",
  "url": "https://www.youtube.com/watch?v=hdMszZ2ah5Q",
  "title": "Macbook PROLED Review: It's Not About That",
  "publishedAt": "2026-11-12",
  "publishedText": "7 days ago",
  "isShort": false,
  "durationSeconds": 914,
  "views": 6400000,
  "isLive": false
}
```

![Videos tab](https://raw.githubusercontent.com/coregentdevspace/youtube-channel-lookup-assets/main/youtube-channel-lookup-output-videos-table-view.png)

**Status values:**

- `ok`: the channel was found and read.
- `ambiguous`: a plain name matched several channels, or none exactly; `candidates` lists up to 5. Not charged.
- `not_found`: no channel exists for that handle, URL, ID or name. Not charged.
- `error`: the data source failed after a retry; `notes` gives the reason. Not charged.

**Good to know:**

- **Rounded numbers:** subscribers, video count and per-video views are rounded the way YouTube displays them
  ("21.4M"). Total views are exact.
- **Estimated dates:** YouTube shows upload dates as "2 weeks ago" or "3 months ago". `publishedAt` is estimated from
  that text and `publishedText` keeps the original. Counts within about 30 days are close; longer windows work in
  month steps. `notes` says when a figure is approximate or a minimum.
- **Shorts have no upload date** on YouTube, so Shorts come back with `publishedAt: null` and don't count toward the
  activity summary.
- **Name lookups:** a name resolves only on an exact match of the channel's title or handle. The result includes
  `resolvedBy: "name"` and up to 4 other `candidates`, so the agent can check it picked the right channel.
- Hidden subscriber counts return `subscribers: null, subscribersHidden: true`. Fields that can't be read are `null`,
  never guessed. No commenter data is returned.

### 💳 Pricing

Pay per event, designed so an agent can budget per channel:

- **Lookup:** once per call that returned the channel (`ok`).
- **Video:** once per video returned. `maxVideos: 0` costs the lookup only.

`ambiguous`, `not_found` and `error` lookups aren't charged, and there's no start fee. Your run's spending limit is
respected: videos are trimmed to fit it. See the **Pricing** tab for current rates (this README deliberately doesn't
quote figures).

### ❓ FAQ

**How fast is it?** Usually a few seconds; a name lookup or a very active channel takes one more request.

**Can I look up many channels?** Call it once per channel; agents loop. For bulk video exports across channels, see
[YouTube Channel Videos Scraper](https://apify.com/coregent/youtube-channel-videos-scraper).

**Does it return contact emails?** It doesn't look for or extract emails. It returns the public links on the channel
page, and the channel description as the creator wrote it, which sometimes includes a business email.

**Does it use the YouTube Data API?** No. The data comes from a third-party YouTube data provider, so you don't need a
Google API key or quota.

### 🔗 Related

- [YouTube Channel Videos Scraper](https://apify.com/coregent/youtube-channel-videos-scraper): every video of a
  channel as rows, for bulk exports.

### ⚖️ Disclaimer

This Actor returns public channel and video information through a third-party YouTube data provider. It is not
affiliated with, endorsed by or sponsored by YouTube or Google. You are responsible for using the data in line with
applicable laws and terms.

# Actor input Schema

## `channel` (type: `string`):

YouTube channel: @handle, channel URL, channel ID (UC…), or name, e.g. @mkbhd. A plain name that matches several channels returns status ambiguous with candidates (free).

## `maxVideos` (type: `integer`):

How many of the newest videos to return (0–60). 0 returns the channel and activity summary only, the cheapest call.

## `videoType` (type: `string`):

Which videos to list: regular uploads (long) or Shorts. The activity summary always uses regular uploads. YouTube shows no upload date for Shorts.

## `sinceDays` (type: `integer`):

Window for the activity summary and the regular-upload list, 7–365 days.

## Actor input object example

```json
{
  "channel": "@MrBeast",
  "maxVideos": 10,
  "videoType": "long",
  "sinceDays": 90
}
```

# Actor output Schema

## `result` (type: `string`):

No description

## `overview` (type: `string`):

No description

## `videos` (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 = {
    "channel": "@MrBeast",
    "maxVideos": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("coregent/youtube-channel-lookup").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 = {
    "channel": "@MrBeast",
    "maxVideos": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("coregent/youtube-channel-lookup").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 '{
  "channel": "@MrBeast",
  "maxVideos": 10
}' |
apify call coregent/youtube-channel-lookup --silent --output-dataset

```

## MCP server setup

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

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/XPnBvjCnz4abHVZ1W/builds/peeNZTcEK8x2yi9Xb/openapi.json
