Tools
Every tool, its inputs and what it returns.
All tools are read-only. Every response is JSON text with the tool's data plus a meta object. Video results include page (the video on viralshooter.com) and youtube (the video on YouTube).
Some tools need full access. Today every signed-in account has full access. A tool that needs it and is called without it returns an error message (isError: true) instead of data.
whoami
Your account, your access, and how fresh the data is. No inputs.
Returns email, name, access (full or public board only), dataAsOf (time of the last update), trackedVideos, trackedChannels, regions (the number of regions polled).
top_videos
The public board: the most-viewed charted videos published in the last 7 days, or the ones first seen on the charts in the last 24 hours (also published in the last 7 days). Sorted by views. Both leave out videos made for kids, age-restricted videos, and the Music and News categories.
| Input | Type | Default | Notes |
|---|---|---|---|
kind | top | new | top | new = first seen in the last 24 hours |
length | short | long | all | short = 3 minutes or less (181 seconds: the API often reports 3:00 videos as 181). A duration filter, not YouTube's Shorts flag |
region | region code | all | See regions |
limit | 1–50 | 20 |
Returns kind, count, videos.
search_videos
Search and filter the tracked videos, like the board. Needs full access.
With q, every word must match (the first 5 words count), in the title, hashtags or channel. Words of 5 or more characters also match close spellings. Results come best match first.
| Input | Type | Default | Notes |
|---|---|---|---|
q | text, ≤ 100 | Words to match in the title, hashtags or channel, e.g. minecraft parkour or #asmr | |
lens | see below | all | A board view |
sort | see below | the lens's own | tenureDays for durable, otherwise views. Ignored when q is set |
dir | asc | desc | desc | For bestRank, best first is the default |
days | 1 | 3 | 7 | 30 | 7 | Published within this many days |
length | short | long | all | |
region | region code | all | |
category | YouTube category id | all | See list_categories |
lang | 2–3 lowercase letters | all | The video's declared language, e.g. en, ko, es |
country | 2 uppercase letters | all | The channel's declared country, e.g. US |
hashtag | text, ≤ 80 | Exact hashtag, with or without # | |
limit | 1–50 | 20 | |
offset | 0–1000 | 0 | For paging |
Lenses: all (every charted video), global (charted in 4 or more regions), northam (charting in the US or Canada, from a channel based in the US or Canada), durable (charted 3 or more days), streamed (streamed or premiered), sponsored (declared paid promotion).
Sorts: views, likes, comments, publishedAt, duration, bestRank, nRegions, tenureDays.
Returns total, sort, count, videos.
get_video
Everything stored about one video. Needs full access.
| Input | Type | Notes |
|---|---|---|
id | 11-character YouTube video id |
Returns video (its fields), viewCurve ([time, views] pairs, last 30 days at most), charts (each region it charted in: rank, first, at, runs), topComments (up to 5: author, text, likes). A video viralshooter does not track returns an error message.
get_channel
One tracked channel. Needs full access.
| Input | Type | Notes |
|---|---|---|
id | YouTube channel id (starts with UC) |
Returns channel (its fields, page, youtube), subscriberCurve ([time, subscribers] pairs, last 30 days at most), videos (its 50 newest videos in the set, charted or not).
search_channels
Find tracked channels by name or @handle. Needs full access.
| Input | Type | Default |
|---|---|---|
q | text, 1–100 | |
limit | 1–20 | 5 |
Returns channels, each with page.
top_hashtags
Hashtags used by the most channels in the tracked set, at least 3 channels each. Generic tags like #shorts are left out.
| Input | Type | Default |
|---|---|---|
length | short | long | all |
region | region code | all |
limit | 1–100 | 30 |
Returns hashtags, each with tag, videos, channels, page.
hashtag
How many charted videos and channels carry a hashtag (all time), and its most-viewed videos (published in the last 30 days).
| Input | Type | Default | Notes |
|---|---|---|---|
tag | text, 1–80 | With or without # | |
limit | 1–50 | 10 |
Returns tag, videoCount, channelCount, videos (empty without full access).
list_categories
YouTube categories present in the tracked set, with how many charted videos each has. No inputs. Returns categories.
list_regions
The chart regions viralshooter polls. No inputs. Returns regions, each with code and name.