SignalYouTube · search/hashtag
Search public YouTube videos for a hashtag. GET /api/v1/youtube/search/hashtag 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 YouTube hashtag pages and returns videos and Shorts that the page exposes. Set type=shorts to keep only items the public page identifies as Shorts; type=all is the default. Pass continuationToken with the same hashtag and type for another public page. This is not a comprehensive or chronological hashtag archive.
| Parameter | Type | Required | Description |
|---|---|---|---|
hashtag | string | Yes | Hashtag text, with or without a leading #. |
type | string | No | Return all public hashtag results or only results identified as Shorts. Allowed: all, shorts. Default: all. |
continuationToken | string | No | Opaque SignalShelf cursor from the previous page. Keep the same hashtag and type. |
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/search/hashtag?hashtag=shorts" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/youtube/search/hashtag?hashtag=shorts", {
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/search/hashtag?hashtag=shorts",
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. data includes platform, resource, sample:false, provider, and the public source payload. Lists return data.items; individual resources return data.data.
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.