Channel Discovery
Billable channel search with filters and pagination.
POST /v1/channels/search
See Concepts โ Discovery and Search Filters.
For allowed category values, see AI Categories.
Full (billable) search.
This is the main discovery endpoint. It allows you to find YouTube channels using filters like category, audience size, country, and more.
You can also enrich results with email contacts by adding a single flag.
Every returned channel includes a top-level has_email boolean. This tells you whether ChannelCrawler has an email available without revealing or charging for the email itself.
There are example curl requests in our Quickstart section
๐ Authorization
You must include your API key:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json๐งช Example: Search by AI category
curl -X POST https://api.channelcrawler.com/v1/channels/search \
-H "Authorization: Bearer $CC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ai_category": ["Gaming"]
}'Optional Enhancements
You can:
Check email availability
Every result includes has_email:
trueโ ChannelCrawler has an email available for this channelfalseโ no email is currently available
When include_email is omitted or false, profile.email is not returned and the channel is billed at the summary rate.
Return email addresses
Add include_email: true to your request.
โข Channels with an email cost 1 credit
โข Channels without an email cost 0.1 credits
โข To return only YouTube channels that we have an email for in our database, add the filter has_email: true
Search specific channels
Use channel_ids or imports_include to fetch data on known YouTube channels.
โข Up to 10,000 channel IDs can be added in one search when using channel_ids as a filter
โข For larger lists, use Imports for faster and more efficient results
โข Learn how to create imports in the Imports section
Exclude known channels
Use exclude_channel_ids or imports_exclude to remove channels you've already worked with.
โข Up to 10,000 channel IDs can be excluded directly when using exclude_channel_ids
โข For longer exclusion lists, use Imports for better performance
โข Learn more in the Imports section
Filter by specific criteria
Narrow your results using fields like:
ai_category, language, country, q
For a full list of available filters, see Search Filters โ Filter Groups.
Sort results
Use sort to change how results are ordered:
subscribers_desc,subscribers_ascviews_desc,views_asclatest_video_desc,latest_video_asc
Search by other social handle
You can search for YouTube channels by linking their other social handles - such as Instagram, Twitter/X, or TikTok profiles.
There are two options:
- Exact match using
external_url - Partial match using
external_url__contains
Response
Each request returns up to 100 YouTube channels in the first page of results.
If more channels match your filters, the response includes a page.next_cursor token.
To retrieve the next page, pass that value as cursor in the next request body. Keep the filters and sort order unchanged between pages.
Pagination is simple:
- Request up to 100 results โ receive the first page plus
page.next_cursor - Send
page.next_cursorback as the request'scursorโ receive the next page - Repeat until
page.next_cursoris absent
You can adjust the number of results by setting the limit (between 1 and 100). The default is 25.
Example result when include_email is omitted:
{
"has_email": true,
"core": {
"channel_id": "UC..."
}
}The actual response includes the rest of the channel data, but not profile.email. Set include_email: true to retrieve it.
Example pagination response:
{
"page": {
"channels": 1,
"with_email": 0,
"cost": 0.1,
"next_cursor": "WzE3MjkxOTYsIlVDLi4uIl0="
},
"results": [
{
"has_email": false,
"core": {
"channel_id": "UC..."
}
}
]
}Use the returned token in the next request:
curl -X POST https://api.channelcrawler.com/v1/channels/search \
-H "Authorization: Bearer $CC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ai_category": ["Gaming"],
"limit": 1,
"cursor": "WzE3MjkxOTYsIlVDLi4uIl0="
}'๐ณ Credit Usage
| Condition | Credits Charged |
|---|---|
| Channel returned (summary only) | 0.1 |
Channel with email (if include_email: true) | 1.0 |
| No channels returned | 0 |
If you request channels with include_email: true, we check each one.
If the email exists, it's charged at 1.0 credit.
If no email exists, it's only 0.1 credit for the channel summary.
If you only want channels that have emails, you must add the has_email: true filter โ otherwise youโll receive a mix of channels, with and without email.