ChannelCrawler API
Core Concepts

Search Filters

Complete list of discovery filters with shapes, dependencies, and examples.

Use these filters with the discovery endpoints:

  • POST /v1/channels/search:preview (free aggregate counts and estimated cost; no channel records)
  • POST /v1/channels/search (billable, 1–100)

The request body is flat JSON. Multiple filters combine with AND. Within a single keyword group, includes are OR’d and excludes become must_not.

Pagination and sorting

  • limit: 1–100 for billable search results
  • cursor: pass next_cursor from the previous response
  • sort: subscribers_desc|subscribers_asc|views_desc|views_asc|latest_video_desc|latest_video_asc
  • accurate_totals: boolean; exact totals at higher cost

Usage tips

  • Use preview first (/v1/channels/search:preview) to gauge volume and cost.
  • When using limit > 50, include at least one narrowing filter: channel_ids, exclude_channel_ids, keywords_include, total_subscribers_min, total_videos_min, active: true, recent_activity_days, or created_days_ago.
  • Date tuple filters (*_days_ago) use [minDays, maxDays] semantics: lte now-minDays and gte now-maxDays.
  • Dependencies:
    • Engagement ranges require engagement_last_videos (10 or 50).
    • Averages ranges require averages_last_videos (10 or 50).
    • Growth ranges require growth_last_days (7, 14, 30, or 90).
  • Advanced filters (exports_*, folders_include, imports_*) require environment indices: EXPORTED_CHANNELS_INDEX, CHANNEL_FOLDERS_INDEX, ELASTICSEARCH_INDEX_IMPORTED_CHANNELS.

Filter groups

Quick links: Channel overview · Categories & niches · Keywords · Engagement · Views · Growth · Email & social · Frequency & duration · Exclusion filters · Imports (advanced)

Channel overview

Examples: Basic search

  • channel_ids: string[] — Filter by specific channel IDs.
    • What it does: Return only channels that match the provided channel IDs. Useful for getting detailed information about specific channels.
  • exclude_channel_ids: string[] — Exclude specific channel IDs from results.
    • What it does: Filter out channels that match the provided channel IDs. Useful for removing known channels from search results.
  • country: string | string[] — Full English country name(s) or ISO 3166-1 alpha-2 code(s). Modern and common names are normalized to indexed labels.
    • What it does: Filter channels based on the country they are associated with. When an array is provided, channels matching any of the countries will be included.
  • exclude_country: string | string[] — Exclude channels by country. Multiple values act as AND (channels matching ANY excluded country are filtered out).
    • What it does: Remove channels from results based on their country. Each exclusion is applied separately.
  • language: string | string[] — Full language name(s), ISO 639-1 code(s), or locale tag(s), such as "English", "en", or "en-US".
    • What it does: Filter channels based on the primary language they use. When an array is provided, channels matching any of the languages will be included.
  • exclude_language: string | string[] — Exclude channels by language. Multiple values act as AND (channels matching ANY excluded language are filtered out).
    • What it does: Remove channels from results based on their primary language. Each exclusion is applied separately.

For canonical country and language names and normalization details, see Supported Values.

  • total_subscribers_min/max: number — Range on core.subscribers.
    • What it does: Filter channels based on their subscriber count.
  • total_views_min/max: number — Range on core.views.
    • What it does: Filter channels based on their total view count across all videos.
  • total_videos_min/max: number — Range on core.videos.
    • What it does: Filter channels based on the total number of videos they have published.
  • created_days_ago: [minDays, maxDays] — Date range on timestamps.created_at.
    • What it does: Filter channels based on when they were added to ChannelCrawler.
  • joined_days_ago: [minDays, maxDays] — Date range on timestamps.joined_at.
    • What it does: Filter channels by how long ago they were created.
  • has_membership: boolean — Term on features.has_membership.
    • What it does: Filter channels based on whether they offer channel memberships.
  • has_shop: boolean — Domain include/exclude of external.links.domain: ["shopify"].
    • What it does: Filter channels based on whether they have a merchandise shop.
  • is_made_for_kids: boolean — Term on features.is_made_for_kids.
  • is_verified: boolean — Term on features.is_verified.

Categories & niches

Examples: Basic search · Exclusion filters

  • ai_category: string[] — Nested OR terms on classification.topics.category_name.
    • See all allowed values: Smart Categories
    • What it does: Filter channels based on specific category topics identified by our AI.
    • Matching is case-insensitive; common aliases such as Tech and Finance are normalized.
  • exclude_ai_category: string[] — Exclude channels by AI-identified category topics. Multiple values act as AND.
    • See all allowed values: Smart Categories
    • What it does: Remove channels from results based on AI-identified category topics.
  • ai_subcategory: string[] — Nested OR terms on classification.topics.subcategory_name.
    • See all allowed values: Smart Subcategories
    • What it does: Filter channels based on specific subcategory topics identified by our AI.
    • Matching is case-insensitive; Crypto and NFT normalize to Cryptocurrency and NFTs.
  • exclude_ai_subcategory: string[] — Exclude channels by AI-identified subcategory topics. Multiple values act as AND.
    • See all allowed values: Smart Subcategories
    • What it does: Remove channels from results based on AI-identified subcategory topics.
  • youtube_category: string | string[] — Term on classification.category.name. Supports single value or array for multiple categories.
    • See all allowed values: YouTube Categories
    • What it does: Filter channels based on their YouTube category. When an array is provided, channels matching any of the categories will be included.
    • Matching is case-insensitive and common aliases such as Tech are normalized.
  • exclude_youtube_category: string | string[] — Exclude channels by category. Multiple values act as AND (channels matching ANY excluded category are filtered out).
    • See all allowed values: YouTube Categories
    • What it does: Remove channels from results based on their YouTube category. Each exclusion is applied separately.

Keywords

Examples: Basic search

  • q: string — Multi-match across channel + video fields.
    • What it does: Search for keywords across all channel content and metadata.
  • keywords_include/exclude: string[] — classification.keywords.
    • What it does: Search in channel #tags.
  • title_keywords_include/exclude: string[] — core.title.
    • What it does: Search in the channel name.
  • description_keywords_include/exclude: string[] — core.description.
    • What it does: Search in the channel bio/description.
  • video_title_keywords_include/exclude: string[] — video_analysis.content.titles.
    • What it does: Search in video titles.
  • video_description_keywords_include/exclude: string[] — video_analysis.content.descriptions.
    • What it does: Search in video descriptions.
  • video_tag_keywords_include/exclude: string[] — video_analysis.content.tags.
    • What it does: Search in video #tags.

Engagement

Examples: Engagement metrics

  • engagement_last_videos: 10 | 50 — Required for any engagement ranges below.
  • engagement_rate_min/max: number — Range on ...engagement_rate_last_<N>.
    • What it does: Percentage of views that are interactions (likes, comments, shares, etc.).
  • engagement_comments_views_ratio_min/max: number — Range on ...comments_views_ratio_last_<N>.
    • What it does: Percentage of views that result in comments.
  • engagement_likes_views_ratio_min/max: number — Range on ...likes_views_ratio_last_<N>.
    • What it does: Percentage of views that result in likes.
  • engagement_views_subs_ratio_min/max: number — Range on ...views_subs_ratio_last_<N>.
    • What it does: Views per subscriber; proxy for audience loyalty.

Views

  • averages_last_videos: 10 | 50 — Required for the ranges below.
  • typical_views_per_video_min/max: number — Range on ...typical_views_per_video_last_<N>.
    • What it does: Median number of views a channel's videos typically receive.
  • views_per_video_min/max: number — Range on ...views_per_video_last_<N>.
    • What it does: Mean number of views across a channel's videos.
  • monthly_views_min/max: number — Range on analytics.monthly_averages.views.month_1.
    • What it does: Average number of views a channel receives per month.
  • monthly_videos_min/max: number — Range on analytics.monthly_averages.videos.month_1.
    • What it does: Average number of videos posted per month.
  • avg_video_length_min/max: number (minutes) — Converted to seconds; range on video_analysis.metrics.averages.length.
    • What it does: Typical duration of videos in minutes.

Growth

  • growth_last_days: 7 | 14 | 30 | 90 — Required for any growth ranges below.
  • growth_subs_count_min/max: number — Range on analytics.growth.subscribers.count.value_<d>d.
    • What it does: Absolute number of new subscribers gained in the selected period.
  • growth_subs_percent_min/max: number — Range on analytics.growth.subscribers.percent.value_<d>d.
    • What it does: Percentage growth in subscribers during the selected period.
  • growth_views_percent_min/max: number — Range on analytics.growth.views.percent.value_<d>d.
    • What it does: Percentage growth in views during the selected period.

Email & social

Examples: Recent activity + social flags

  • has_email: boolean — Exists on profile.email (false adds must_not exists).
    • What it does in a request: Filters by whether an email is available on ChannelCrawler.
    • The same name appears as a top-level boolean on every search result, indicating whether an email can be retrieved without exposing it.
  • has_view_email: boolean — Term on features.has_view_email.
    • What it does: Filters by whether YouTube exposes its "View email address" feature; it does not guarantee that ChannelCrawler has a retrievable email.
  • has_instagram|has_tiktok|has_facebook|has_snapchat|has_linkedin|has_twitter|has_discord|has_twitch|has_pinterest: boolean — Domain include/exclude on external.links.domain (e.g., ["instagram"], ["twitter","x"], etc.).
    • What it does: Filter channels that have linked these social accounts.

Frequency & duration

Examples: Recent activity + social flags

  • active: boolean — When true, timestamps.latest_video_date >= now-60d/d.
    • What it does: Filter by how recently they posted a video.
  • recent_activity_days: number — GTE range on timestamps.latest_video_date since now.
    • What it does: Filter channels with activity in the last N days.
  • latest_video_days_ago: [minDays, maxDays] — Date range on timestamps.latest_video_date.

Imports (advanced)

  • imports_include/imports_exclude: string[] — Use import IDs returned by /v1/imports.
    • What it does: Include/exclude channels from previous imported batches.

Note: Advanced filters require those environment indices to be configured.

Examples

Channel IDs filtering

Filter by specific channel IDs or exclude certain channels:

# Include specific channels
curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "channel_ids": ["UCX6OQ3DkcsbYNE6H8uQQuVA", "UCq-Fj5jknLsUf-MWSy4_brA"],
    "limit": 10
  }'

# Exclude specific channels from tech search
curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "q": "tech",
    "exclude_channel_ids": ["UCX6OQ3DkcsbYNE6H8uQQuVA", "UCq-Fj5jknLsUf-MWSy4_brA"],
    "limit": 25
  }'
import requests, os

# Include specific channels
resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "channel_ids": ["UCX6OQ3DkcsbYNE6H8uQQuVA", "UCq-Fj5jknLsUf-MWSy4_brA"],
    "limit": 10,
  },
  timeout=15,
)
print(resp.json())

# Exclude specific channels from tech search
resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "q": "tech",
    "exclude_channel_ids": ["UCX6OQ3DkcsbYNE6H8uQQuVA", "UCq-Fj5jknLsUf-MWSy4_brA"],
    "limit": 25,
  },
  timeout=15,
)
print(resp.json())
// Include specific channels
const resp1 = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_ids: ["UCX6OQ3DkcsbYNE6H8uQQuVA", "UCq-Fj5jknLsUf-MWSy4_brA"],
    limit: 10,
  }),
});
console.log(await resp1.json());

// Exclude specific channels from tech search
const resp2 = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "tech",
    exclude_channel_ids: ["UCX6OQ3DkcsbYNE6H8uQQuVA", "UCq-Fj5jknLsUf-MWSy4_brA"],
    limit: 25,
  }),
});
console.log(await resp2.json());

Basic search: keywords + classification + ranges

curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "q": "tech",
    "youtube_category": "Science & Technology",
    "country": "United States",
    "language": "English",
    "total_subscribers_min": 50000,
    "total_views_min": 1000000,
    "limit": 25,
    "sort": "subscribers_desc"
  }'
import requests, os

resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "q": "tech",
    "youtube_category": "Science & Technology",
    "country": "United States",
    "language": "English",
    "total_subscribers_min": 50000,
    "total_views_min": 1_000_000,
    "limit": 25,
    "sort": "subscribers_desc",
  },
  timeout=15,
)
print(resp.json())
const resp = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "tech",
    youtube_category: "Science & Technology",
    country: "United States",
    language: "English",
    total_subscribers_min: 50000,
    total_views_min: 1000000,
    limit: 25,
    sort: "subscribers_desc",
  }),
});
console.log(await resp.json());

Multiple values for country, language, and category

You can now provide arrays for country, language, and category parameters to search across multiple values:

curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "q": "tech",
    "youtube_category": ["Science & Technology", "Gaming"],
    "country": ["United States", "United Kingdom"],
    "language": ["English", "Spanish"],
    "total_subscribers_min": 50000,
    "limit": 25
  }'
import requests, os

resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "q": "tech",
    "youtube_category": ["Science & Technology", "Gaming"],
    "country": ["United States", "United Kingdom"],
    "language": ["English", "Spanish"],
    "total_subscribers_min": 50000,
    "limit": 25,
  },
  timeout=15,
)
print(resp.json())
const resp = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "tech",
    youtube_category: ["Science & Technology", "Gaming"],
    country: ["United States", "United Kingdom"],
    language: ["English", "Spanish"],
    total_subscribers_min: 50000,
    limit: 25,
  }),
});
console.log(await resp.json());
curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type": "application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "q": "tech",
    "youtube_category": "Science & Technology",
    "country": "United States",
    "language": "English",
    "total_subscribers_min": 50000,
    "total_views_min": 1000000,
    "limit": 25,
    "sort": "subscribers_desc"
  }'
import requests, os

resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "q": "tech",
    "youtube_category": "Science & Technology",
    "country": "United States",
    "language": "English",
    "total_subscribers_min": 50000,
    "total_views_min": 1_000_000,
    "limit": 25,
    "sort": "subscribers_desc",
  },
  timeout=15,
)
print(resp.json())
const resp = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "tech",
    youtube_category: "Science & Technology",
    country: "United States",
    language: "English",
    total_subscribers_min: 50000,
    total_views_min: 1000000,
    limit: 25,
    sort: "subscribers_desc",
  }),
});
console.log(await resp.json());

Engagement metrics (requires engagement_last_videos)

curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type": "application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "keywords_include": ["review", "unboxing"],
    "engagement_last_videos": 10,
    "engagement_rate_min": 0.04,
    "engagement_likes_views_ratio_min": 0.02,
    "limit": 25,
    "sort": "latest_video_desc"
  }'
import requests, os

payload = {
  "keywords_include": ["review", "unboxing"],
  "engagement_last_videos": 10,
  "engagement_rate_min": 0.04,
  "engagement_likes_views_ratio_min": 0.02,
  "limit": 25,
  "sort": "latest_video_desc",
}

resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={"Authorization": f"Bearer {os.environ['CC_API_KEY']}", "Content-Type": "application/json"},
  json=payload,
  timeout=15,
)
print(resp.json())
const payload = {
  keywords_include: ["review", "unboxing"],
  engagement_last_videos: 10,
  engagement_rate_min: 0.04,
  engagement_likes_views_ratio_min: 0.02,
  limit: 25,
  sort: "latest_video_desc",
};

const resp = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await resp.json());

Recent activity + social flags

curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type": "application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "recent_activity_days": 30,
    "has_instagram": true,
    "has_tiktok": true,
    "has_email": true,
    "limit": 25
  }'
import requests, os

payload = {
  "recent_activity_days": 30,
  "has_instagram": True,
  "has_tiktok": True,
  "has_email": True,
  "limit": 25,
}

resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={"Authorization": f"Bearer {os.environ['CC_API_KEY']}", "Content-Type": "application/json"},
  json=payload,
  timeout=15,
)
print(resp.json())
const payload = {
  recent_activity_days: 30,
  has_instagram: true,
  has_tiktok: true,
  has_email: true,
  limit: 25,
};

const resp = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await resp.json());

Exclusion filters: exclude specific values

Exclusion filters let you remove channels from results based on categories, countries, languages, or topics. Multiple exclusions act as AND — channels matching ANY excluded value are filtered out.

# Exclude specific categories
curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "youtube_category": "Science & Technology",
    "exclude_youtube_category": ["Gaming", "Music"],
    "total_subscribers_min": 10000,
    "limit": 25
  }'

# Exclude countries and languages
curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "country": ["United States", "Canada", "Mexico"],
    "exclude_language": "Spanish",
    "total_subscribers_min": 50000,
    "limit": 25
  }'

# Combine inclusion and exclusion for precise targeting
curl -X POST \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.channelcrawler.com/v1/channels/search \
  -d '{
    "ai_category": ["Tech, AI & Software"],
    "exclude_ai_subcategory": ["Cryptocurrency", "NFTs"],
    "exclude_country": ["United States", "United Kingdom"],
    "total_subscribers_min": 100000,
    "limit": 25
  }'
import requests, os

# Exclude specific categories
resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "youtube_category": "Science & Technology",
    "exclude_youtube_category": ["Gaming", "Music"],
    "total_subscribers_min": 10000,
    "limit": 25,
  },
  timeout=15,
)
print(resp.json())

# Exclude countries and languages
resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "country": ["United States", "Canada", "Mexico"],
    "exclude_language": "Spanish",
    "total_subscribers_min": 50000,
    "limit": 25,
  },
  timeout=15,
)
print(resp.json())

# Combine inclusion and exclusion for precise targeting
resp = requests.post(
  "https://api.channelcrawler.com/v1/channels/search",
  headers={
    "Authorization": f"Bearer {os.environ['CC_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "ai_category": ["Tech, AI & Software"],
    "exclude_ai_subcategory": ["Cryptocurrency", "NFTs"],
    "exclude_country": ["United States", "United Kingdom"],
    "total_subscribers_min": 100000,
    "limit": 25,
  },
  timeout=15,
)
print(resp.json())
// Exclude specific categories
const resp1 = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    youtube_category: "Science & Technology",
    exclude_youtube_category: ["Gaming", "Music"],
    total_subscribers_min: 10000,
    limit: 25,
  }),
});
console.log(await resp1.json());

// Exclude countries and languages
const resp2 = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country: ["United States", "Canada", "Mexico"],
    exclude_language: "Spanish",
    total_subscribers_min: 50000,
    limit: 25,
  }),
});
console.log(await resp2.json());

// Combine inclusion and exclusion for precise targeting
const resp3 = await fetch("https://api.channelcrawler.com/v1/channels/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ai_category: ["Tech, AI & Software"],
    exclude_ai_subcategory: ["Cryptocurrency", "NFTs"],
    exclude_country: ["United States", "United Kingdom"],
    total_subscribers_min: 100000,
    limit: 25,
  }),
});
console.log(await resp3.json());

How exclusion filters work:

  • exclude_youtube_category: ["Gaming", "Music"] means: NOT Gaming AND NOT Music
  • Channels with Gaming OR Music category will be excluded
  • Works alongside inclusion filters for precise targeting
  • Each exclusion value is applied separately (AND logic)