ChannelCrawler API
API Reference

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 channel
  • false โ€” 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_asc
  • views_desc, views_asc
  • latest_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_cursor back as the request's cursor โ†’ receive the next page
  • Repeat until page.next_cursor is 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

ConditionCredits Charged
Channel returned (summary only)0.1
Channel with email (if include_email: true)1.0
No channels returned0

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.