GET
/
v1
/
viral-library
/
posts
/
{postId}
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.viralLibrary.getViralPost({
  postId: process.env.OCTOSPARK_POST_ID ?? "postId",
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "<string>",
  "creatorHandle": "<string>",
  "hook": "<string>",
  "caption": "<string>",
  "language": "<string>",
  "postedAt": "<string>",
  "metrics": {
    "playCount": 123,
    "likeCount": 123,
    "commentCount": 123,
    "shareCount": 123,
    "saveCount": 123,
    "snapshotAt": "<string>"
  },
  "engagementRate": 123,
  "coverUrl": "<string>",
  "enrichment": {
    "productName": "<string>",
    "adSignal": {
      "reason": "<string>"
    },
    "creatorSponsored": true,
    "channelFollowers": 123
  },
  "extras": {},
  "media": [
    {
      "position": 123,
      "url": "<string>",
      "contentType": "<string>",
      "width": 123,
      "height": 123,
      "durationMs": 123
    }
  ]
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

postId
string<uuid>
required

Post id (UUID), as returned by the list viral posts endpoint.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Response

Success

id
string<uuid>
required

Stable OctoSpark id of the post; use it with the get post endpoint.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
platform
enum<string>
required

Social platform the post was published on.

Available options:
tiktok,
youtube,
instagram,
linkedin,
x,
threads
url
string
required

Public URL of the original post on its platform.

creatorHandle
string | null
required

Handle of the posting account, without the leading @; null when not captured.

hook
string | null
required

Opening line or on-screen hook of the post; null when not captured.

caption
string | null
required

Full caption or body text; null when not captured.

format
enum<string>
required

What the post is made of: slideshow, video, image_post or text_post.

Available options:
slideshow,
video,
image_post,
text_post
kind
enum<string>
required

The platform's own post kind, such as photo mode versus video on TikTok.

Available options:
photo,
video,
text
category
enum<string> | null
required

Content category slug; null for posts whose source corpus had no categories.

Available options:
arts-hobbies-entertainment,
health-wellness,
education-knowledge,
relationships-lifestyle,
personal-development,
fashion-beauty,
technology,
business-finance,
spirituality-beliefs,
fitness,
food-cooking,
travel,
home-design,
gaming-esports,
productivity-organization
origin
enum<string>
required

Which corpus the post was mirrored from.

Available options:
genviral,
reelfarm,
content_ranker
language
string | null
required

BCP 47 language tag of the text, when detected.

postedAt
string | null
required

ISO-8601 time the post went live on its platform; null when unknown.

metrics
object
required

Engagement counts as captured at the snapshot; each count is null when the platform did not report it.

engagementRate
number | null
required

Likes, comments, shares and saves divided by plays; null when plays are unknown or zero.

coverUrl
string | null
required

Public URL of the cover image; null when no cover is stored.

enrichment
object
required

Monetisation and sponsorship labels from the source corpus.

extras
object
required

Platform-specific scalars without a dedicated field, such as dislikes, keyed by their source name.

media
object[]
required

Slides and video of the post in display order; file URLs are present only on the full tier.