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 resultscursor: passnext_cursorfrom the previous responsesort:subscribers_desc|subscribers_asc|views_desc|views_asc|latest_video_desc|latest_video_ascaccurate_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, orcreated_days_ago. - Date tuple filters (
*_days_ago) use[minDays, maxDays]semantics: ltenow-minDaysand gtenow-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).
- Engagement ranges require
- 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 ontimestamps.created_at.- What it does: Filter channels based on when they were added to ChannelCrawler.
- joined_days_ago:
[minDays, maxDays]— Date range ontimestamps.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
TechandFinanceare 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;
CryptoandNFTnormalize toCryptocurrencyandNFTs.
- 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
Techare 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_datesince now.- What it does: Filter channels with activity in the last N days.
- latest_video_days_ago:
[minDays, maxDays]— Date range ontimestamps.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)