Skip to main content
GET
Search the viral library: Genviral’s curated corpus of organic TikTok, Instagram, and Threads 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.

​
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, or threads.
​
string
slideshow, video, or mixed.
​
string
Match posts whose account handle contains this text.
​
string
Match posts whose product name contains this text.
​
number
Return only posts with at most this many slides. Range: 1-100.
​
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 and 900 single-post 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