SignalYouTube · channel/search
Search public videos within a YouTube channel. GET /api/v1/youtube/channel/search accepts your x-api-key header. Production live requests are disabled pending source and commercial-use authorization, including cross-channel use.
Request parameters
Reads public channel search results for the supplied handle. Returns publicly listed videos and playlists. Pass the returned continuationToken with the same handle and query for the next page; private content is not accessible.
| Parameter | Type | Required | Description |
|---|---|---|---|
handle | string | Yes | Public YouTube channel handle, with or without @. |
query | string | Yes | Words to search within the channel. |
continuationToken | string | No | Opaque SignalShelf cursor from the previous response. Keep the same handle and query. |
freshness | string | No | 24h (default), 1h, 7d, or live. Accepted cache hits are free; live forces refresh except simultaneous requests may share newly fetched data. |
Code examples
Set SIGNALSHELF_BASE_URL and SIGNALSHELF_API_KEY on your server.
curl "$SIGNALSHELF_BASE_URL/api/v1/youtube/channel/search?handle=NASA&query=artemis" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/youtube/channel/search?handle=NASA&query=artemis", {
headers: { 'x-api-key': process.env.SIGNALSHELF_API_KEY },
});
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data, body.meta);import os, requests
response = requests.get(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/v1/youtube/channel/search?handle=NASA&query=artemis",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
timeout=30,
)
response.raise_for_status()
print(response.json())Response and pagination
The response contains data and meta. Search results are grouped into data.videos, data.shorts, data.lives, data.channels and data.playlists; groups the public page does not expose are empty arrays.
Search responses contain data.videos, data.shorts, data.lives, data.channels and data.playlists arrays, with only groups exposed by the source populated. When YouTube provides a continuation, data.continuationToken is an opaque SignalShelf-signed cursor; pass it unchanged with the same query, and for channel search the same handle. A null token means the source exposed no next page. Cursor pagination is implemented, but reference filters, popular sorting and includeExtras are not.
meta includes event_id, mode, cache, credits_charged, fetched_at, age_seconds, and duration_ms. A fresh successful result costs one credit; accepted cached results and failures cost zero.
Availability and failures
Implementation is not a continuous availability guarantee. Source rate limits, retention, deleted content, restrictions, and regional availability apply. This is an independent SignalShelf contract, not a drop-in competitor response format.
400: invalid parameters. 401: missing/revoked key. 402: insufficient credits. 404: missing public resource. 429: SignalShelf throttle. 502/503: upstream failure or rate limit, with credit restored.