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.
Spoken transcripts stay out of this response. Read one explicitly with
Get Viral Library Transcript.
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