Core Concepts
Discovery
Find new channels using filters and keywords.
Find new channels using filters and keywords.
- Endpoints:
- POST
/v1/channels/search:preview(free aggregate counts and estimated cost; no channel records) - POST
/v1/channels/search(billable, limit 1–100)
- POST
For allowed category values, see AI Categories. For country and language values, see Supported Values.
Search Filters let you refine YouTube channel discovery by applying precise criteria — from location and category to growth rate, engagement, and even video-level keywords.
How It Works
- The request body is flat JSON.
- Multiple filters are combined with AND logic.
- Lists (like
q) are treated as OR inside that filter. - Use
limit,cursor, andsortto control pagination and ordering. - Some filters require supporting parameters see dependencies below.
Pagination and Sorting Options
| Field | Description |
|---|---|
limit | Number of channels to return from the billable search (1–100) |
cursor | Pass next_cursor from the previous response |
sort | One of: subscribers_desc, subscribers_asc, views_desc, views_asc, latest_video_desc, latest_video_asc |
Filter Dependencies
Some filters depend on others to work correctly:
| Filter Range Type | Requires | Notes |
|---|---|---|
| Engagement | engagement_last_videos (10 or 50) | Must be set to use any engagement filter |
| Views | averages_last_videos (10 or 50) | Required for per-video or monthly views |
| Growth | growth_last_days (7, 14, 30, 90) | Required for any growth ranges |
For the complete list of filters, shapes, and dependencies (engagement/averages/growth), see Core Concepts → Search Filters.