YouTube Channel Research API Tutorial | SandBase

If you research creators on YouTube, you want a repeatable loop: search videos for a topic, resolve the channels behind the strong results, and read each channel’s public stats to rank them. This YouTube Channel Research API tutorial wires that loop with two SandBase endpoints so an agent can run it end to end. It builds on the YouTube public data API hub; read that first for the big picture.

Everything here is public, read-only data. There is no YouTube login and no SDK — a SandBase API key is still required to authenticate. The endpoint API reference is the source of truth for parameters and the response envelope. The reference guarantees only that envelope; the payload field names below come from calls I ran (tested on 2026-09-28, UTC) and are illustrative, observed-only — not documented guarantees — so confirm them against a live response.

Key takeaway

• Two endpoints form the loop: search-video (find videos) → channel-info (channel stats).
• Each call is POST /v1/api/youtube/web/<path>, one SANDBASE_API_KEY.
• Chain by natural inputs: a search_query drives search; a video’s channel_id becomes the input for channel-info.
• Page the search with the returned continuation_token. Public, read-only data only.

SandBase vs. the official YouTube Data API

Your need	Use
Public, read-only search and channel stats	SandBase YouTube public-data API
Manage a channel, upload, or use quota-based Data API	YouTube’s official Data API
Private or account-only data	Neither public workflow

The workflow at a glance

1. Search videos with youtube/web/search-video using a search_query.
2. Read the channel with youtube/web/channel-info using a video’s channel_id.

Each endpoint returns the shared envelope — an id, a status, the model, and the payload on a completed run.

The YouTube endpoints on SandBase — search-video and channel-info drive this loop.

Step 0: one helper for every call

import os
import requests

API = "https://api.sandbase.ai/v1/api"
HEADERS = {
    "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
    "Content-Type": "application/json",
}

def call(path: str, payload: dict) -> dict:
    resp = requests.post(f"{API}/{path}", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    if body.get("status") != "completed":
        raise RuntimeError(body.get("error", {}).get("message", f"{path} did not complete"))
    # Envelope can vary: prefer a top-level `output`, else `outputs[0].data`.
    output = body.get("output")
    if output is None and body.get("outputs"):
        output = body["outputs"][0].get("data", {})
    return output or {}

Step 1: search videos

data = call("youtube/web/search-video", {"search_query": "machine learning tutorial"})
videos = data.get("videos", [])
token = data.get("continuation_token")
for v in videos[:5]:
    print(v.get("title"), "-", v.get("author"), "|", v.get("number_of_views"), "views")

In the response I captured (search run id a8b82dc1-190d-4560-9fa2-3c98878bfad4, tested on 2026-09-28, UTC), the payload carried a videos list, plus continuation_token and number_of_videos. Each video carried video_id, title, author, channel_id, number_of_views, published_time, and video_length — illustrative, observed-only fields. Read each with .get().

To page, resend search-video with the returned continuation_token — confirm the exact parameter name against the reference.

The search-video reference — the source of truth for the search_query parameter and paging.

Step 2: read the channel

channel_ids = {v.get("channel_id") for v in videos if isinstance(v, dict) and v.get("channel_id")}

for cid in list(channel_ids)[:5]:
    channel = call("youtube/web/channel-info", {"channel_id": cid})
    print(channel.get("title"), "|", channel.get("subscriber_count"), "subs,", channel.get("video_count"), "videos")

The channel-info endpoint takes a channel_id — a video’s channel_id works directly. In my run (channel-info run id eca232e4-ce65-45eb-ab7f-6da2c99c16bc), the payload carried title, subscriber_count, video_count, view_count, verified, creation_date, and country — illustrative, observed-only fields the reference does not guarantee.

The channel-info reference — pass a channel_id; a search result’s channel_id works as that identifier.

Putting it together

def research(query: str, max_channels: int = 5):
    data = call("youtube/web/search-video", {"search_query": query})
    videos = data.get("videos", [])
    seen, channels = set(), []
    for v in videos:
        if not isinstance(v, dict):
            continue
        cid = v.get("channel_id")
        if cid and cid not in seen:
            seen.add(cid)
            channels.append(call("youtube/web/channel-info", {"channel_id": cid}))
        if len(channels) >= max_channels:
            break
    return channels

Because both endpoints share the same envelope, the loop stays flat: one status check in call(...) and the channel_id flowing from a video into the channel lookup.

Common use cases

Creator shortlisting

Search a niche topic, collect the channel_ids from strong videos, and rank the channels by subscriber_count and video_count to build a shortlist. Input: a search_query. Output: ranked channel stats. Endpoints: search-video, channel-info.

Competitor benchmarking

Read a set of channels’ subscriber_count, view_count, and creation_date to benchmark growth and output against competitors. Input: channel ids. Output: comparable channel stats. Endpoint: channel-info.

Topic coverage mapping

Search a topic and inspect the videos payload — titles, view counts, and channels — to map who covers a subject and how much reach they have. Input: a search_query. Output: a video sample with channels. Endpoint: search-video.

Practical notes

• Envelope can vary. The reference documents outputs[0].data; read either shape (prefer output, fall back to outputs[0].data).
• Page with the token. Resend search-video with continuation_token while more results exist.
• Business fields are observed-only. Treat videos, channel_id, subscriber_count, and the like as observed and confirm live.
• Public, read-only data only. No uploads, no private/account-only data. Authenticate with a SandBase API key.
• Be a good client. Retry with backoff on transient errors such as HTTP 429; page rather than hammering.

FAQ

Do I need a YouTube/Google API key or quota? No. You authenticate to SandBase with your SANDBASE_API_KEY. These read endpoints need no Google Cloud project or Data API quota on your side.

How do I get from a video to its channel? Each video in the search payload carries a channel_id; pass it to channel-info.

How do I page through more videos? The search payload carries a continuation_token; resend search-video with it. Confirm the exact parameter against the reference.

Can I read private or unlisted videos? No. The API returns public data only. Private and account-authorized content are out of scope.

Wrap up

Two endpoints, one envelope, a channel_id flowing between steps — that is the whole channel-research loop. For the full endpoint catalog, see the YouTube public data API hub. When you are ready:

• Get a SandBase API key
• Browse the YouTube endpoints
• Open the search-video API reference