Skip to main content
GET
Search the viral library: Genviral’s curated corpus of organic TikTok, Instagram, Threads, and YouTube Shorts posts that passed 10,000 views, kept with their metrics, slide images, hook, and hook analysis. Every post in the corpus is organic content from a real account, selected and classified by Genviral. Nothing in it is generated, sponsored, or paid. Search results do not contain spoken transcripts. Once a result is worth deeper analysis, read that one script with Get Viral Library Transcript.

​
Searching by idea, not by keyword

q is a natural-language idea, not a keyword match. The corpus is indexed by what a post is about, so cooking app finds meal-planning walkthroughs whose captions never use either word, and skincare founder story finds a founder talking about her product without saying “founder”. Ordering follows from that: results are ordered by relevance whenever q is present, and by newest otherwise. Set sort explicitly to override either default. Filters compose with q rather than replacing it. Narrowing by category, business_type, platform, account, or the publish dates is almost always a better way to find a specific post than paging deep into a broad query.

​
Query Parameters

​
string
A natural-language idea to search for, 1-200 characters — for example cooking app, productivity app onboarding, skincare founder story. When set, results are ordered by relevance.
​
string
One content category, for example Food & Cooking, Technology, or Health & Wellness. See the enum in the OpenAPI schema for the full list.
​
string
What the post is selling: app, ecommerce, saas, service, affiliate, creator, game, book, other, or unclassified.
​
string
tiktok, instagram, threads, or youtube (YouTube Shorts).
​
string
slideshow, video, or mixed.
​
string
Match posts whose account handle contains this text.
​
string
Match posts whose product name contains this text.
​
string
Comma-separated numeric App Store ids, up to 100. Returns only posts tied to any of these apps through their App Store link, website or product name — the same association each post’s product_app reports.
​
number
Return only posts with at most this many slides. Range: 1-100.
​
string
TikTok paid reach. ads: posts TikTok served as ads. likely_or_ads: also posts whose creator authorized Spark Ads or whose engagement looks like paid reach. not_ads: neither. Posts never checked (every Instagram, Threads, and YouTube post) count as not ads.
​
boolean
true returns only posts a brand paid a creator to make (a paid-partnership label, a disclosure hashtag such as #ad, or a promo code); false hides them. Posts never checked count as not sponsored.
​
string
Content language: one or more ISO 639-1 codes, comma-separated (en,es), up to 20. mul matches bilingual posts, zxx posts with no spoken or written words, and und posts whose language could not be determined. A post matches when its language is any of the codes.
​
string
Earliest publish date, as a calendar date YYYY-MM-DD. This is the day the post went out, not the day Genviral captured it.
​
string
Latest publish date, as a calendar date YYYY-MM-DD. Must be at or after published_since.
​
string
relevance, newest, latest_posted, most_views, most_likes, most_comments, or most_slides. Defaults to relevance when q is set and newest otherwise.
​
number
default:"12"
Posts per page. Range: 1-40.
​
number
default:"0"
Posts to skip. Range: 0-960.

​
Response

​
array
Matching posts, ordered by sort.
​
number
Total posts matching the query, not the size of this page.
​
boolean
​
number | null
The offset for the next page, or null on the last page and once the reachable window is exhausted. At the reach cap a response can carry has_more: true alongside next_offset: null: more posts match, but none of them are reachable on this query — narrow it with filters instead.

​
Reach and rate limits

One query reaches at most 1,000 results: offset is capped at 960 and limit at 40. total still reports the full match count, so a query whose total runs into the thousands is a query to narrow, not a query to page through. Add a category, a business_type, a platform, an account, or a published_since/published_until window and search again. Reads are rate limited per authenticated customer: The results budget is the one to plan around. A search is charged its requested limit before it runs — asking for 40 spends 40 whether or not 40 come back — so the 2,000 rows a day are yours to spend on wide pages or on many narrow ones. Request an honest limit rather than the maximum, and the budget lasts. A ceiling also applies across all callers together — 300 searches, 900 single-post reads, and 300 transcript reads per minute — so a burst can be throttled even while your own budget is intact. Every limit answers 429 with error_code: "rate_limited" and a retry_after_seconds value. Wait that long before retrying; retrying sooner consumes budget without returning results. A 503 provider_unavailable means the limiter itself could not be reached. The daily budget is counted centrally, so a request that cannot be counted is refused rather than served. It is transient, and carries its own retry_after_seconds.

​
Error Responses

  • 401 - authentication failed (missing, invalid, or revoked token)
  • 402 subscription_required - an active eligible subscription is required
  • 403 tier_not_allowed - the Scheduler tier cannot use the Partner API
  • 422 - invalid query parameters, for example an unknown category, an offset above 960, or a published_until before published_since
  • 429 rate_limited - the per-customer request limit, the daily results budget, or the shared ceiling was reached; wait retry_after_seconds and retry
  • 503 provider_unavailable - the rate limiter was unreachable, so the request was refused rather than served uncounted; wait retry_after_seconds and retry