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

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

CODEBLOCK0

1. 2. Set API key:

CODEBLOCK1

Get this key from viral.app dashboard at Settings -> API Keys.

1. 3. Verify access:

CODEBLOCK2

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:

CODEBLOCK3

Common reads:

CODEBLOCK4

Common mutations:

CODEBLOCK5

Payout mutation flow:

CODEBLOCK6

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:

CODEBLOCK7

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 - INLINECODE33

Common routes:

• - Analytics overview filtered by tracked account:

CODEBLOCK8

• - Analytics accounts filtered by tracked account:

CODEBLOCK9

• - Analytics videos filtered by tracked account:

CODEBLOCK10

• - Analytics videos filtered by tracked account and date range:

CODEBLOCK11

• - Tracked video detail page:

CODEBLOCK12

• - Analytics overview filtered by creator-owned tracked accounts:

CODEBLOCK13

• - Creator Hub creators filtered by campaign:

CODEBLOCK14

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

CODEBLOCK15

• - Creator Hub campaigns filtered by creator:

CODEBLOCK16

• - Creator Hub campaign detail page:

CODEBLOCK17

• - Creator Hub payouts filtered by creator:

CODEBLOCK18

• - Creator Hub payouts filtered by campaign:

CODEBLOCK19

• - Creator Hub upcoming payouts filtered by creator and campaign:

CODEBLOCK20

• - Other payout tabs preserve the same filters:

CODEBLOCK21

• - Viral video library filtered list:

CODEBLOCK22

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

CODEBLOCK23

• - Viral video library detail page:

CODEBLOCK24

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 - INLINECODE74

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 or -H "x-api-key: ..." value.
• INLINECODE84 can also happen with expired/revoked keys or wrong org context.
• INLINECODE85 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.