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

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

const response = await client.viralLibrary.listViralPosts({
  query: {},
})
{
  "data": [
    {
      "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
      }
    }
  ],
  "total": 123,
  "nextCursor": "<string>",
  "prevCursor": "<string>",
  "pageOffset": 123
}

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
cursor
string

Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page.

​
offset
string

Zero-based row offset to jump to (numbered pages), 0 to 10000. With a cursor, the jump starts from that cursor; without one it is a plain offset. Lists not yet on the signed cursor standard ignore it.

Examples:

"0"

"25"

​
limit
string
default:25

Page size as a positive integer string; defaults to 25, capped at 100.

Examples:

"25"

"100"

​
sortBy
enum<string>

Sort key: playCount (the default, most-played first), likeCount, commentCount, shareCount, saveCount, postedAt or engagementRate. Keys other than playCount require an active subscription.

Available options:
playCount,
likeCount,
commentCount,
shareCount,
saveCount,
postedAt,
engagementRate
Examples:

"playCount"

"postedAt"

​
sortOrder
enum<string>
default:desc

Sort direction: asc or desc; defaults to desc.

Available options:
asc,
desc
​
filter[platform]
string

Only posts from these platforms: one value or a comma-separated list of tiktok, youtube, instagram, linkedin, x, threads. Values and counts come from the facets endpoint.

Examples:

"tiktok"

"tiktok,instagram"

​
filter[category]
string

Only posts in these content category slugs: one value or a comma-separated list. Values and counts come from the facets endpoint.

Examples:

"fitness"

"fitness,travel"

​
filter[format]
string

Only posts of these formats: one value or a comma-separated list of slideshow, video, image_post, text_post.

Examples:

"slideshow"

"slideshow,video"

​
filter[origin]
string

Only posts mirrored from these corpora: one value or a comma-separated list of genviral, reelfarm, content_ranker.

Examples:

"genviral"

"genviral,reelfarm"

​
filter[kind]
string

Only posts of these platform kinds: one value or a comma-separated list of photo, video, text.

Examples:

"video"

"photo,video"

​
filter[monetization]
string

Only posts with these monetisation labels: one value or a comma-separated list of app, ecommerce, affiliate, saas, other. Unlabelled posts never match.

Examples:

"app"

"app,saas"

​
filter[adSignal]
string

Only posts with these advert classifications: ad, likely_ad or none (no signal recorded), one value or a comma-separated list.

Examples:

"none"

"ad,likely_ad"

​
filter[sponsored]
enum<string>

Only posts whose creator was marked sponsored (true) or not sponsored (false); posts with an unknown sponsorship never match.

Available options:
true,
false
​
filter[language]
string

Only posts in these detected languages: one BCP 47 code or a comma-separated list, each 2 to 8 characters, as listed by the facets endpoint.

Examples:

"en"

"en,de"

​
filter[postedAfter]
string

Only posts published on or after this calendar date (YYYY-MM-DD, UTC). Posts with an unknown publish time never match.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2025-01-31"

​
filter[postedBefore]
string

Only posts published on or before this calendar date (YYYY-MM-DD, UTC). Posts with an unknown publish time never match.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2025-01-31"

​
filter[minPlays]
string

Only posts with at least this many plays (a non-negative integer). Posts with unreported plays never match.

Pattern: ^\d+$
Example:

"100000"

​
filter[minLikes]
string

Only posts with at least this many likes (a non-negative integer). Posts with unreported likes never match.

Pattern: ^\d+$
Example:

"100000"

​
filter[minSaves]
string

Only posts with at least this many saves (a non-negative integer). Posts with unreported saves never match.

Pattern: ^\d+$
Example:

"100000"

​
filter[q]
string

Full-text search over creator handle, hook and caption using web search syntax (quoted phrases, OR, a leading minus to exclude), at most 200 characters. Requires an active subscription.

Maximum string length: 200
Examples:

"morning routine"

"\"side hustle\" -crypto"

Response

Success

​
data
object[]
required
​
total
number
required
​
nextCursor
string | null
required

Opaque cursor for the page after this one; null on the last page.

​
prevCursor
string | null
required

Opaque cursor for the page before this one; null on the first page. Lists on the signed cursor standard return a real backwards cursor; older lists echo the request cursor.

​
pageOffset
number | null

Zero-based position of the first row of this page within total (for "Showing 26-50 of 268" and page numbers); null when unknown.