Outlier video search

Search stored data by keyword, niche, region, and views-to-subscribers ratio.

POST

https://api.shortsmonkey.com/v1/videos/outliers/search

0 Credits

Outlier video search#

Search stored data by keyword, niche, region, and views-to-subscribers ratio.

Authentication#

Send Authorization: Bearer sm_live_.... Never place the full key in URLs, cookies, bodies, logs, or analytics.

Data freshness#

Rankings read stable snapshots published by the worker. Public reads never trigger a YouTube refresh.

Request#

Item	Value	Description
Method	`POST`	HTTP request method
Full URL	`https://api.shortsmonkey.com/v1/videos/outliers/search`	Production API URL
Authentication	`Authorization: Bearer sm_live_...`	Send the full key only in the header
Content type	`application/json`	The request body uses JSON
Credits	0 Credits	All operations cost 0 credits. There is no monthly credit grant or commercial credit deduction.

Request parameters#

Name	Location	Type	Required	Default	Values or limits	Description
`keyword`	JSON body	`string`	No	—	1–120 characters	Keyword matched against stored title or niche text
`niche`	JSON body	`string`	No	—	1–80 characters	Niche or category filter
`video_type`	JSON body	`string`	No	`all`	`shorts` / `long` / `all`	Video type
`region`	JSON body	`string`	No	—	2–16 characters	Region code
`max_channel_subscribers`	JSON body	`integer`	No	—	`0–10,000,000`	Maximum channel subscriber count
`min_views`	JSON body	`integer`	No	—	`0–1,000,000,000`	Minimum view count
`min_vs_ratio`	JSON body	`number`	No	`10`	`0–100,000`	Minimum views-to-subscribers ratio
`time_window`	JSON body	`string`	No	`7d`	`24h` / `3d` / `7d` / `30d`	Video publication window
`limit`	JSON body	`integer`	No	`20`	`1–50`	Maximum number of items on this page
`all_cursor`	JSON body	`string`	No	—	`data.all_data.next_cursor`	Fetch the next unfiltered page
`filter_cursor`	JSON body	`string`	No	—	`data.filter_data.next_cursor`	Fetch the next filtered page without changing filters
`cursor`	JSON body	`string`	No	—	Deprecated compatibility parameter	Alias for `filter_cursor`; do not send both

Success response fields#

all_data is an unfiltered page from the stable snapshot; filter_data is a page from the same snapshot after endpoint defaults and request filters. Each result paginates independently.

All operations cost 0 credits. There is no monthly credit grant or commercial credit deduction.

Field path	Type	Nullable	Description
`data.all_data.items`	`array<object>`	No	Unfiltered video items on the current page
`data.all_data.items[].video_id`	`string`	No	YouTube video ID
`data.all_data.items[].title`	`string`	No	Video title
`data.all_data.items[].video_url`	`string`	No	YouTube video URL
`data.all_data.items[].channel.id`	`string`	Yes	Channel ID
`data.all_data.items[].channel.title`	`string`	No	Channel title
`data.all_data.items[].channel.subscribers`	`integer`	Yes	Subscriber count; `null` when hidden
`data.all_data.items[].channel.subscriber_count_hidden`	`boolean`	No	Whether the subscriber count is hidden
`data.all_data.items[].views`	`integer`	No	View-count snapshot
`data.all_data.items[].views_to_subscribers_ratio`	`number`	Yes	Views-to-subscribers ratio
`data.all_data.items[].opportunity_score`	`number`	Yes	Opportunity score
`data.all_data.items[].duration_seconds`	`integer`	No	Video duration in seconds
`data.all_data.items[].published_at`	`string(date-time)`	Yes	Video publication time in UTC ISO 8601
`data.all_data.items[].snapshot_at`	`string(date-time)`	Yes	Data collection time
`data.all_data.items[].niche`	`string`	Yes	Niche or category
`data.all_data.items[].track`	`string`	Yes	Dataset track identifier
`data.all_data.items[].region`	`string`	Yes	Region code
`data.all_data.items[].reasons`	`array<string>`	No	Ranking reasons
`data.all_data.items[].video_type`	`string`	No	`shorts` or `long`
`data.all_data.next_cursor`	`string`	Yes	Next-page cursor for this result set; `null` when finished
`data.filter_data.items`	`array<object>`	No	Video items after defaults and request filters
`data.filter_data.items[].video_id`	`string`	No	YouTube video ID
`data.filter_data.items[].title`	`string`	No	Video title
`data.filter_data.items[].video_url`	`string`	No	YouTube video URL
`data.filter_data.items[].channel.id`	`string`	Yes	Channel ID
`data.filter_data.items[].channel.title`	`string`	No	Channel title
`data.filter_data.items[].channel.subscribers`	`integer`	Yes	Subscriber count; `null` when hidden
`data.filter_data.items[].channel.subscriber_count_hidden`	`boolean`	No	Whether the subscriber count is hidden
`data.filter_data.items[].views`	`integer`	No	View-count snapshot
`data.filter_data.items[].views_to_subscribers_ratio`	`number`	Yes	Views-to-subscribers ratio
`data.filter_data.items[].opportunity_score`	`number`	Yes	Opportunity score
`data.filter_data.items[].duration_seconds`	`integer`	No	Video duration in seconds
`data.filter_data.items[].published_at`	`string(date-time)`	Yes	Video publication time in UTC ISO 8601
`data.filter_data.items[].snapshot_at`	`string(date-time)`	Yes	Data collection time
`data.filter_data.items[].niche`	`string`	Yes	Niche or category
`data.filter_data.items[].track`	`string`	Yes	Dataset track identifier
`data.filter_data.items[].region`	`string`	Yes	Region code
`data.filter_data.items[].reasons`	`array<string>`	No	Ranking reasons
`data.filter_data.items[].video_type`	`string`	No	`shorts` or `long`
`data.filter_data.next_cursor`	`string`	Yes	Next-page cursor for this result set; `null` when finished
`meta.request_id`	`string`	No	Request trace ID
`meta.snapshot_id`	`string`	No	Stable snapshot ID
`meta.snapshot_at`	`string(date-time)`	No	Snapshot timestamp
`meta.data_status`	`string`	No	Dataset status
`credits.cost`	`integer`	No	All operations cost 0 credits. There is no monthly credit grant or commercial credit deduction.
`credits.remaining`	`integer` \| null	Yes	`null`
`credits.period_ends_at`	`string(date-time)` \| null	Yes	`null`
`credits.unlimited`	`boolean`	No	`true`

Send all_data.next_cursor as all_cursor and filter_data.next_cursor as filter_cursor. The cursors are independent, opaque, signed, and valid for 24 hours; legacy cursor is only an alias for filter_cursor.

ETag#

Rankings support If-None-Match. A hit returns HTTP 304 with X-Credits-Cost: 0.

Errors and rate limits#

Every error contains code, stable English message, request_id, and details. All 4xx/5xx responses cost zero credits.

HTTP status	Code	Cause	Suggested action
400	`INVALID_REQUEST`	Invalid parameter format, combination, or range	Correct the parameters using `details.issues`
401	`INVALID_API_KEY`	The key is invalid or inactive	Check the Bearer header and key status
429	`API_DAILY_LIMIT_REACHED`	All API keys on an account share 10 daily REST data calls. The allowance resets at 00:00 Asia/Shanghai. The website has its own separate allowance of 10 searches per day. MCP uses neither allowance.	`API_DAILY_LIMIT_REACHED` returns HTTP 429 after 10 REST data calls. Wait until 00:00 Asia/Shanghai; creating or rotating a key does not reset the account allowance.
429	`RATE_LIMITED`	Rate or concurrency limit exceeded	Retry after the `Retry-After` interval
503	`DATA_STALE` / `SERVICE_UNAVAILABLE`	Data or service is temporarily unavailable	Retry later and retain `request_id`

curl -X POST "https://api.shortsmonkey.com/v1/videos/outliers/search" \
  -H "Authorization: Bearer $SHORTSMONKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"finance","video_type":"all","time_window":"7d","min_vs_ratio":10,"limit":20}'