ChannelCrawler API
API Reference

Imports

Create imports of channel IDs and use them in search with imports_include/imports_exclude.

Import batches of channel IDs and reference them in search filters using imports_include and imports_exclude.

POST /v1/imports — Create an import

Use this endpoint to upload large lists of channel IDs so you can enrich, exclude, or deduplicate those channels in future searches.


Best For

  • Enriching known YouTube channels at scale
  • Excluding channels you've already contacted

CSV Format

To upload a file, the CSV must contain a single column with the header channel_id.

Example:

channel_id
UC_x5XG1OV2P6uZZ5FSM9Ttw
UCVHFbqXqoYvEWM1Ddxl0QDg

You can upload up to 200,000 channel_ids in a single import.

If you have more than that, you’ll need to break your list into separate files.

The reason we ask this is simple: processing multiple smaller imports is significantly faster than handling one large file — and that means a smoother, quicker experience for you.


Create an Import

How to create an import

1. Direct list (server-side)

Use this method to submit a list of channel IDs directly in your request. You must give it a name, and then provide all the channel IDs you wish to include.

curl -X POST https://api.channelcrawler.com/v1/imports \
  -H "Authorization: Bearer $CC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Highest Subs Channels",
    "channel_ids": [
      "UCX6OQ3DkcsbYNE6H8uQQuVA",
      "UCq-Fj5jknLsUf-MWSy4_brA"
    ]
  }'

Check Import Status

List All Imports

GET /v1/imports

Query parameters:

  • limit (number, 1–100, default: 25): Maximum number of imports to return
  • status (string, optional): Filter by import status
    • Values: pending, processing, completed, or failed
  • file_name (string, optional): Filter by file name (case-insensitive partial match)
  • created_from (string, optional): Filter imports created on or after this date (ISO 8601 datetime)
  • created_to (string, optional): Filter imports created on or before this date (ISO 8601 datetime)

Example request with filters:

curl -X GET "https://api.channelcrawler.com/v1/imports?status=completed&file_name=leads&created_from=2025-01-01T00:00:00Z&created_to=2025-12-31T23:59:59Z" \
  -H "Authorization: Bearer $CC_API_KEY"

Example response:

{
  "imports": [
    {
      "id": "abc123",
      "name": "Leads Import",
      "status": "processing",
      "total_records": 123,
      "processed": 0,
      "success": 0,
      "failed": 0,
      "progress": 0,
      "error": null}
  ]
}

Check a Single Import

GET /v1/imports/:id

Returns the current status and progress of the specified import.


Once imported, you can reference these IDs in /v1/channels/search or /v1/channels/search:preview.

  • imports_include: string[] — only return channels that match your import
  • imports_exclude: string[] — exclude channels in your import from results

Additional filters can be used in conjunction with both of these parameters