Chinese low-subscriber long videos
A dedicated opportunity ranking that returns Strict items by default.
GET
https://api.shortsmonkey.com/v1/rankings/chinese-low-subscriber-long-videos?start_date=2026-07-01&end_date=2026-07-20&quality=strict&limit=201 credit per actual 1–20 items
Chinese low-subscriber long videos#
A dedicated opportunity ranking that returns Strict items by default.
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 | GET | HTTP request method |
| Full URL | https://api.shortsmonkey.com/v1/rankings/chinese-low-subscriber-long-videos?start_date=2026-07-01&end_date=2026-07-20&quality=strict&limit=20 | Production API URL |
| Authentication | Authorization: Bearer sm_live_... | Send the full key only in the header |
| Content type | No request body | GET requests have no request body |
| Credits | 1 credit per actual 1–20 items | Error responses cost 0 credits |
Request parameters#
| Name | Location | Type | Required | Default | Values or limits | Description |
|---|---|---|---|---|---|---|
period | Query | string | No | today | today / 7d / all_time | Preset publication window; omit when using custom dates |
start_date | Query | string(date) | Conditional | — | YYYY-MM-DD | Inclusive UTC start date; must be paired with end_date |
end_date | Query | string(date) | Conditional | — | YYYY-MM-DD | Inclusive UTC end date; cannot be earlier than the start date |
track | Query | string | No | all | 1–80 characters | Filter by track identifier; all includes every track |
quality | Query | string | No | strict | strict / all | Return strict data only or include expanded candidates |
limit | Query | integer | No | 20 | 1–50 | Maximum number of items on this page |
all_cursor | Query | string | No | — | all_data.next_cursor, valid for 24 hours | Fetch the next unfiltered page |
filter_cursor | Query | string | No | — | filter_data.next_cursor, valid for 24 hours | Fetch the next filtered page without changing filters |
cursor | Query | 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.
Dot notation represents nested objects and [] represents array items. Unknown subscriber counts are null with subscriber_count_hidden: true. One request is billed once using the larger returned item count, never the sum of both sets.
| 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 |
data.all_data.items[].quality_tier | string | No | strict or expanded |
data.filter_data.items[].quality_tier | string | No | strict or expanded |
data.all_data.items[].is_expanded_candidate | boolean | No | Whether the item is an expanded candidate |
data.filter_data.items[].is_expanded_candidate | boolean | No | Whether the item is an expanded candidate |
meta.methodology_version | string | No | Ranking methodology version |
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 | Actual credits charged |
credits.remaining | integer | No | Remaining account credits |
credits.period_ends_at | string(date-time) | No | Current credit-period end |
Pagination and cursors#
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 |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | Subscription or credits are unavailable | Check the plan, balance, and key safety budget |
| 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 GET "https://api.shortsmonkey.com/v1/rankings/chinese-low-subscriber-long-videos?start_date=2026-07-01&end_date=2026-07-20&quality=strict&limit=20" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"