ChannelCrawler API
API Reference

Search Preview

Free aggregate preview of channel search counts and estimated cost.

POST /v1/channels/search:preview

This is a free aggregate preview endpoint. It returns matching channel counts and estimated credit cost without using any credits. It does not return individual channel records or sample channels.

Use this to:

  • Preview the number of channel results you would obtain on search execution
  • Check that filters are working as expected
  • Avoid wasting credits on bad searches

πŸ” Authorization

Include your API key as always:

Authorization: Bearer $CC_API_KEY
Content-Type: application/json

πŸ§ͺ Example: Preview number of results when searching by keyword, category and country

curl -X POST https://api.channelcrawler.com/v1/channels/search:preview \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "automation",
    "ai_category": ["Tech, AI & Software"],
    "country": "United States",
    "total_subscribers_min": 50000,
    "sort": "subscribers_desc"
  }'

How Preview Works

  • Free to run β€” you’re never charged, even if include_email: true
  • With include_email: true, the response includes aggregate counts and estimated cost for channels with and without available emails
  • Never returns channel records or email contacts
  • Shows an estimated cost, but does not deduct credits

This lets you see:

  • The exact credits you’d be billed for
  • Whether your search is too broad or too narrow

πŸ” Response

Each preview request returns:

  • An estimated_cost field that shows how many credits the full search would use
  • A totals field that tells you how many YouTube channels match your search criteria

Example:

{
    "json": {
        "totals": {
            "channels": 1633,
            "with_email": 989,
            "without_email": 644
        },
        "estimated_cost": {
            "with_email": 989,
            "without_email": 64.4,
            "total": 1053.4
        }
    }
}
  • totals β€” shows how many YouTube channels matched your search.
  • estimated_cost β€” estimated credits if this was a full search.

πŸ†“ Credit Usage

ConditionCredits Charged
Any preview request0 (always free)

Even when using include_email: true, preview requests do not use credits. Email contacts and sample channel records are never shown in preview.


⚑ Rate Limits

Preview requests are subject to rate limiting to prevent abuse:

  • Per-IP limit: 60 requests per minute (configurable via RATE_LIMIT_RPM)
  • Per-user limit: 30 requests per minute (configurable via PREVIEW_RATE_LIMIT_RPM)
  • Daily user limit: 500 requests per day (configurable via PREVIEW_DAILY_LIMIT)

If you exceed these limits, you'll receive a 429 Too Many Requests response.


🚫 Restrictions

The preview endpoint does not support channel-specific filters. The following filters will return a 400 Bad Request error:

  • channel_id
  • channel_ids
  • external_url
  • external_urls
  • external_url__contains

These filters are designed for precise channel lookups, not for previewing search results. Use the standard /v1/channels/search endpoint instead if you need to query specific channels.


Best For

  • Validating your filters before running a full search
  • Understanding how many YouTube channels match your criteria
  • Comparing different targeting strategies without using credits


Tip: Use before you spend

Preview is the fastest way to check if your search is working.

Use it to see result counts, fine-tune your filters, and avoid wasting credits on poor targeting.