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_costfield that shows how many credits the full search would use - A
totalsfield 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
| Condition | Credits Charged |
|---|---|
| Any preview request | 0 (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_idchannel_idsexternal_urlexternal_urlsexternal_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.