viral-app

Use this skill when you need to read or manage data through the viral.app API.

When to use

Query analytics (accounts, videos, KPIs, exports).
Manage tracked entities (accounts, videos, exclusions, refresh runs).
Manage projects and creator hub resources.
Pull live platform data (Facebook, TikTok, Instagram, YouTube).

Quick start

Ensure
```
viral-app
```
CLI is installed and available in
```
PATH
```
.

bash

viral-app --help

Set API key:

bash

export VIRAL_API_KEY="..."

Get this key from viral.app dashboard at

Settings -> API Keys

Verify access:

bash

viral-app accounts-list --per-page 1

The wrapper injects

x-api-key

automatically from

VIRAL_API_KEY

unless a header is already passed.

Inputs to collect first

Task type: read/report or mutate/manage resources.
Org-scoped IDs:
```
orgacc_*
```
,
```
orgproj_*
```
, creator/campaign/payout IDs when relevant.
Platform and entity identifiers (
```
facebook|tiktok|instagram|youtube
```
, platform account/video IDs).
Time bounds (
```
--date-range[from]
```
,
```
--date-range[to]
```
) for analytics tasks.
Pagination/scope (
```
--per-page
```
, filters) to keep output focused.

Command cookbook

Discover available operations:

bash

viral-app --help
viral-app <command> --help

Common reads:

bash

viral-app accounts-list --per-page 10
viral-app videos-list --per-page 10
viral-app analytics-get-kpis
viral-app analytics-top-videos --per-page 10
viral-app integrations-apps-list

Common mutations:

bash

viral-app projects-create --body '{"name":"My Project"}'
viral-app accounts-tracked-refresh --body '{"accounts":["orgacc_..."]}'
viral-app projects-add-to-account --body '{"projectId":"orgproj_...","accountId":"orgacc_..."}'

Payout mutation flow:

bash

viral-app payouts-calculate --body '{"campaignId":"orgcamp_...","creatorId":"orgcre_...","billingPeriodStart":"2026-03-01T00:00:00.000Z","billingPeriodEnd":"2026-03-31T00:00:00.000Z"}'
viral-app payouts-initiate --body '{"campaignId":"orgcamp_...","creatorId":"orgcre_...","billingPeriodStart":"2026-03-01T00:00:00.000Z","billingPeriodEnd":"2026-03-31T00:00:00.000Z","lineItems":[{"title":"Creator payout","amount":1496.62}],"calculation":{...},"integrityToken":"..."}'

Rules for payout mutations:

Always call
```
payouts-calculate
```
immediately before
```
payouts-initiate
```
.
Pass the returned
```
calculation
```
payload and
```
integrityToken
```
into
```
payouts-initiate
```
unchanged.
Do not invent or recompute
```
integrityToken
```
.

If using

autoApproveTalentir=true

, also set

acknowledgeFullPayoutLiability=true

and explain the risk before executing.

Prefer review-first behavior for payout mutations unless the user explicitly asks to initiate or approve payouts.

Report templates

Use the bundled report templates when the user asks for Slack-ready summaries or ranking reports:

Leaderboard template: assets/templates/leaderboard.md
Leaderboard example: assets/examples/leaderboard-sample.md
Viral Video Library template: assets/templates/viral-video-library-report.md
Viral Video Library example: assets/examples/viral-video-library-report-sample.md
Creator payments + CPM template: assets/templates/creator-payments-cpm-report.md
Creator payments + CPM example: assets/examples/creator-payments-cpm-report-sample.md

Rules for leaderboard-style outputs:

Follow the template structure unless the user explicitly asks for a different format.
Use analytics account links for account-level leaderboard sections.
Use tracked video detail links for video leaderboard sections.
Keep numbers compact, for example
```
1.4M
```
or
```
180K
```
.
Use period-over-period trend markers where the comparison window is available.
Prefer returning the rendered report plus the source viral.app links when useful.

Rules for Viral Video Library reports:

Use linked titles that point to the Viral Video Library detail page.
Use abbreviated metrics, for example
```
473K
```
or
```
18.2%
```
.
Include a hashtags line for every entry.

Use a single hook line in the form

Hook (<archetype>): text + visual + audio

Do not use "Audio not surfaced" phrasing.
Do not invent fields when insights are missing; use
```
not confidently detected
```
.

Rules for creator payments + CPM reports:

Use current in-progress upcoming payouts from Creator Hub for the ranking section.
Use Creator Hub payout links filtered by both
```
creatorIds
```
and
```
campaigns
```
.
Compare each payout row against the most recent completed payout window for the same creator and campaign when available.
Use current vs previous equal-length periods for org-wide KPI deltas.
Keep payout amounts exact, view totals compact, Effective CPM to 4 decimals, and spend per video to 2 decimals.

Linking Back Into viral.app

When a user would benefit from opening the data in the product UI, include a direct viral.app app link in your response.

Default production base:

text

https://viral.app/app

Rules:

Prefer linking to the most specific page the app actually supports.
For tracked videos and library videos, use dedicated detail pages.
For accounts and creators, prefer filtered list/dashboard views. The app does not currently expose a dedicated account detail page or creator detail page route.
For multi-value filters, use comma-separated values in a single query param.
For date ranges on analytics and creator-hub overview pages, use
```
df
```
and
```
dt
```
with
```
YYYY-MM-DD
```
.
Preserve
```
viewMode
```
when linking account or creator-related analytics:
- ```
internal
```
- ```
competitors
```
- ```
all
```

Common routes:

Analytics overview filtered by tracked account:

text

https://viral.app/app/analytics/overview?accounts=<orgAccountId>&viewMode=internal

Analytics accounts filtered by tracked account:

text

https://viral.app/app/analytics/accounts?accounts=<orgAccountId>&viewMode=internal

Analytics videos filtered by tracked account:

text

https://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal

Analytics videos filtered by tracked account and date range:

text

https://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal&df=2026-03-01&dt=2026-03-18

Tracked video detail page:

text

https://viral.app/app/analytics/videos/tiktok/7491234567890123456

Analytics overview filtered by creator-owned tracked accounts:

text

https://viral.app/app/analytics/overview?accounts=<orgAccountId1>,<orgAccountId2>&viewMode=all

Creator Hub creators filtered by campaign:

text

https://viral.app/app/creator-hub/creators?campaigns=<campaignId>

Creator Hub creators filtered by search and include archived/inactive creators:

text

https://viral.app/app/creator-hub/creators?search=alex%40example.com&status=all

Creator Hub campaigns filtered by creator:

text

https://viral.app/app/creator-hub/campaigns?creatorIds=<orgCreatorId>

Creator Hub campaign detail page:

text

https://viral.app/app/creator-hub/campaigns/<campaignId>

Creator Hub payouts filtered by creator:

text

https://viral.app/app/creator-hub/payouts/due?creatorIds=<orgCreatorId>

Creator Hub payouts filtered by campaign:

text

https://viral.app/app/creator-hub/payouts/due?campaigns=<campaignId>

Creator Hub upcoming payouts filtered by creator and campaign:

text

https://viral.app/app/creator-hub/payouts/upcoming?creatorIds=<orgCreatorId>&campaigns=<campaignId>

Other payout tabs preserve the same filters:

text

https://viral.app/app/creator-hub/payouts/upcoming?creatorIds=<orgCreatorId>
https://viral.app/app/creator-hub/payouts/canceled?campaigns=<campaignId>
https://viral.app/app/creator-hub/payouts/paid?creatorIds=<orgCreatorId>

Viral video library filtered list:

text

https://viral.app/app/library/viral-videos?search=notion&dateRange=30d&sort=views

Viral video library filtered by brand/region/minimum views:

text

https://viral.app/app/library/viral-videos?brandId=<brandId>&regions=US,GB&minViews=100000&sort=outlier

Viral video library detail page:

text

https://viral.app/app/library/viral-videos/tiktok/7491234567890123456

Supported filter keys you can safely use:

Analytics overview/accounts/videos:

```
accounts
```
```
platforms
```
```
projects
```
```
contentTypes
```
```
viewMode
```
```
df
```
```
dt
```

Analytics overview only:

```
publicationMode
```
```
topVideosBy
```
```
topAccountsBy
```
```
topCreatorsBy
```
```
topEntity
```
```
topListsPerPage
```

Creator Hub creators:
- ```
search
```
- ```
campaigns
```
- ```
status
```
Creator Hub campaigns:
- ```
search
```
- ```
status
```
- ```
creatorIds
```

Creator Hub overview / campaign overview:

```
campaigns
```
```
creatorIds
```
```
scope
```
```
publicationMode
```
```
df
```
```
dt
```

Creator Hub payouts:
- ```
creatorIds
```
- ```
campaigns
```

Viral video library:

```
search
```
```
brandId
```
```
dateRange
```
```
sort
```
```
minViews
```
```
minOutlierFactor
```
```
regions
```
```
productTypes
```
```
verticals
```
```
formats
```
```
hookArchetypes
```
```
productDetected
```
```
brandDetected
```
```
matchedTerms
```

If you do not know the correct org-scoped IDs yet:

link to the closest filtered list you can build confidently
say what the link shows
avoid inventing unknown IDs or unsupported paths

Safety rules

Confirm intent before
```
POST
```
,
```
PUT
```
,
```
PATCH
```
, or
```
DELETE
```
unless the user explicitly asked for that mutation.
Run
```
<command> --help
```
before mutations to verify required flags and body schema.
Prefer narrow queries first (
```
--per-page
```
, filters, date ranges) before broad exports.
Keep output machine-readable by default; only switch format when requested.

Troubleshooting

401 UNAUTHORIZED

: missing/invalid API key; verify

VIRAL_API_KEY

-H "x-api-key: ..."

value.

```
401
```
can also happen with expired/revoked keys or wrong org context.
```
429
```
or retry hints: back off and retry later; inspect response headers such as
```
Retry-After
```
.
Empty
```
data
```
arrays: validate filters, project/account IDs, and date range constraints.
Never expose API keys in commits; rotate keys after sharing for tests.

Agent defaults

Output defaults to JSON (
```
RSH_OUTPUT_FORMAT=json
```
unless overridden).
Auto-pagination defaults to disabled (
```
RSH_NO_PAGINATE=true
```
) for predictable scripted behavior.
Summarize key metrics after reads and explicitly call out write-side effects after mutations.

viral-app

NPX Install

Tags

SKILL.md Content

viral-app

When to use

Quick start

Inputs to collect first

Command cookbook

Report templates

Linking Back Into viral.app

Safety rules

Troubleshooting

Agent defaults