curl --request GET \
--url 'https://www.genviral.io/api/partner/v1/viral-library/viral-post-1' \
--header 'Authorization: Bearer <token>'
{
"ok": true,
"code": 200,
"message": "Viral library post retrieved",
"data": {
"id": "viral-post-1",
"platform": "tiktok",
"content_type": "slideshow",
"link": "https://www.tiktok.com/@chefdesk/video/1",
"category": "Food & Cooking",
"business_type": "app",
"product_name": "Chef Desk",
"product_website": "https://chefdesk.example",
"account": "chefdesk",
"caption": "The 3 meals I batch on Sunday",
"hashtags": ["mealprep", "cookingapp"],
"date_published": "2026-07-14",
"metrics": {
"views": 412000,
"likes": 38000,
"comments": 900,
"shares": 1200,
"bookmarks": 5400
},
"slide_count": 6,
"preview_image_url": "https://cdn.example.com/viral/preview-1.jpg",
"image_urls": ["https://cdn.example.com/viral/slide-1.jpg"],
"video_url": null,
"hook_text": "I stopped cooking every night",
"hook_analysis": {
"content_class": "listicle",
"format_template": "problem-solution",
"psychology_tags": ["relief", "time-saving"]
},
"search_summary": "A batch-cooking app walkthrough told as a Sunday routine",
"niche": "meal planning",
"topics": ["batch cooking"],
"search_keywords": ["meal prep app"],
"slide_texts": [
"I stopped cooking every night",
"Sunday: 3 bases, 40 minutes",
"Monday to Thursday: assemble only"
],
"relevance": null
}
}
Viral Library
Get Viral Library Post
Read one viral library post by ID, including the slide texts a search result omits
GET
/
api
/
partner
/
v1
/
viral-library
/
{postId}
curl --request GET \
--url 'https://www.genviral.io/api/partner/v1/viral-library/viral-post-1' \
--header 'Authorization: Bearer <token>'
{
"ok": true,
"code": 200,
"message": "Viral library post retrieved",
"data": {
"id": "viral-post-1",
"platform": "tiktok",
"content_type": "slideshow",
"link": "https://www.tiktok.com/@chefdesk/video/1",
"category": "Food & Cooking",
"business_type": "app",
"product_name": "Chef Desk",
"product_website": "https://chefdesk.example",
"account": "chefdesk",
"caption": "The 3 meals I batch on Sunday",
"hashtags": ["mealprep", "cookingapp"],
"date_published": "2026-07-14",
"metrics": {
"views": 412000,
"likes": 38000,
"comments": 900,
"shares": 1200,
"bookmarks": 5400
},
"slide_count": 6,
"preview_image_url": "https://cdn.example.com/viral/preview-1.jpg",
"image_urls": ["https://cdn.example.com/viral/slide-1.jpg"],
"video_url": null,
"hook_text": "I stopped cooking every night",
"hook_analysis": {
"content_class": "listicle",
"format_template": "problem-solution",
"psychology_tags": ["relief", "time-saving"]
},
"search_summary": "A batch-cooking app walkthrough told as a Sunday routine",
"niche": "meal planning",
"topics": ["batch cooking"],
"search_keywords": ["meal prep app"],
"slide_texts": [
"I stopped cooking every night",
"Sunday: 3 bases, 40 minutes",
"Monday to Thursday: assemble only"
],
"relevance": null
}
}
Read one post from Genviral’s curated corpus of organic viral posts.
This is the only place
slide_texts is served. A search page omits it so a page
of results stays small, so reading the words on a post’s slides is a deliberate
second call once the search has told you which post is worth it.
Every other field matches
Search Viral Library exactly.
Path Parameters
string
required
A post
id returned by
Search Viral Library.Response
The response is one viral library post object.string
string
string
string | null
string
string | null
string | null
string | null
string | null
string | null
string[]
string | null
Calendar date,
YYYY-MM-DD.object
views, likes, comments, shares, and bookmarks, each a number or
null where the platform did not report it.number | null
string | null
string[]
Slide images, in order.
string | null
Present only when the clip is available for playback.
string | null
The opening line the post leads with.
object | null
content_class, format_template, and psychology_tags.string | null
string | null
string[]
string[]
string[] | null
The text on each slide, in order.
null for a post with no slide text.null
Reserved. The ranking score is not exposed.
Rate limits
Single-post reads are limited to 60 per minute and 300 per day per authenticated customer, with a ceiling of 900 per minute across all callers together. A throttled request answers429 with error_code: "rate_limited"
and a retry_after_seconds value; wait that long before retrying.
These reads spend no part of the search budget.
Search Viral Library carries its own
allowance of 2,000 results a day, and each search is charged its requested
limit, so read a post here rather than re-running a search to see it again.
A 503 provider_unavailable means the limiter itself could not be reached.
The daily budgets are counted centrally, so a request that cannot be counted is
refused rather than served. It is transient, and carries its own
retry_after_seconds.
curl --request GET \
--url 'https://www.genviral.io/api/partner/v1/viral-library/viral-post-1' \
--header 'Authorization: Bearer <token>'
{
"ok": true,
"code": 200,
"message": "Viral library post retrieved",
"data": {
"id": "viral-post-1",
"platform": "tiktok",
"content_type": "slideshow",
"link": "https://www.tiktok.com/@chefdesk/video/1",
"category": "Food & Cooking",
"business_type": "app",
"product_name": "Chef Desk",
"product_website": "https://chefdesk.example",
"account": "chefdesk",
"caption": "The 3 meals I batch on Sunday",
"hashtags": ["mealprep", "cookingapp"],
"date_published": "2026-07-14",
"metrics": {
"views": 412000,
"likes": 38000,
"comments": 900,
"shares": 1200,
"bookmarks": 5400
},
"slide_count": 6,
"preview_image_url": "https://cdn.example.com/viral/preview-1.jpg",
"image_urls": ["https://cdn.example.com/viral/slide-1.jpg"],
"video_url": null,
"hook_text": "I stopped cooking every night",
"hook_analysis": {
"content_class": "listicle",
"format_template": "problem-solution",
"psychology_tags": ["relief", "time-saving"]
},
"search_summary": "A batch-cooking app walkthrough told as a Sunday routine",
"niche": "meal planning",
"topics": ["batch cooking"],
"search_keywords": ["meal prep app"],
"slide_texts": [
"I stopped cooking every night",
"Sunday: 3 bases, 40 minutes",
"Monday to Thursday: assemble only"
],
"relevance": null
}
}
Error Responses
401- authentication failed (missing, invalid, or revoked token)402 subscription_required- an active eligible subscription is required403 tier_not_allowed- the Scheduler tier cannot use the Partner API404- no post with this ID is in the library422-postIdis missing or longer than 300 characters429 rate_limited- the per-customer or shared rate limit was reached; waitretry_after_secondsand retry503 provider_unavailable- the rate limiter was unreachable, so the request was refused rather than served uncounted; waitretry_after_secondsand retry