{"skill":{"slug":"viral-app","displayName":"Viral App","summary":"Use the viral.app API from an agent with a local CLI for account analytics, tracked videos/accounts, projects, creator hub, and live data operations.","description":"---\nname: viral-app\ndescription: Use the viral.app API from an agent with a local CLI for account analytics, tracked videos/accounts, projects, creator hub, and live data operations.\nhomepage: https://github.com/fmd-labs/viral-app-skills/tree/main/viral-app\nmetadata: {\"openclaw\":{\"homepage\":\"https://github.com/fmd-labs/viral-app-skills/tree/main/viral-app\",\"requires\":{\"bins\":[\"viral-app\"],\"env\":[\"VIRAL_API_KEY\"]},\"primaryEnv\":\"VIRAL_API_KEY\"}}\n---\n\n# viral-app\n\nUse this skill when you need to read or manage data through the viral.app API.\n\n## When to use\n\n- Query analytics (accounts, videos, KPIs, exports).\n- Manage tracked entities (accounts, videos, exclusions, refresh runs).\n- Manage projects and creator hub resources.\n- Pull live platform data (Facebook, TikTok, Instagram, YouTube).\n\n## Quick start\n\n1. Ensure `viral-app` CLI is installed and available in `PATH`.\n\n```bash\nviral-app --help\n```\n\n2. Set API key:\n\n```bash\nexport VIRAL_API_KEY=\"...\"\n```\n\nGet this key from viral.app dashboard at `Settings -> API Keys`.\n\n3. Verify access:\n\n```bash\nviral-app accounts-list --per-page 1\n```\n\nThe wrapper injects `x-api-key` automatically from `VIRAL_API_KEY` unless a header is already passed.\n\n## Inputs to collect first\n\n- Task type: read/report or mutate/manage resources.\n- Org-scoped IDs: `orgacc_*`, `orgproj_*`, creator/campaign/payout IDs when relevant.\n- Platform and entity identifiers (`facebook|tiktok|instagram|youtube`, platform account/video IDs).\n- Time bounds (`--date-range[from]`, `--date-range[to]`) for analytics tasks.\n- Pagination/scope (`--per-page`, filters) to keep output focused.\n\n## Command cookbook\n\nDiscover available operations:\n\n```bash\nviral-app --help\nviral-app <command> --help\n```\n\nCommon reads:\n\n```bash\nviral-app accounts-list --per-page 10\nviral-app videos-list --per-page 10\nviral-app analytics-get-kpis\nviral-app analytics-top-videos --per-page 10\nviral-app integrations-apps-list\n```\n\nCommon mutations:\n\n```bash\nviral-app projects-create --body '{\"name\":\"My Project\"}'\nviral-app accounts-tracked-refresh --body '{\"accounts\":[\"orgacc_...\"]}'\nviral-app projects-add-to-account --body '{\"projectId\":\"orgproj_...\",\"accountId\":\"orgacc_...\"}'\n```\n\nPayout mutation flow:\n\n```bash\nviral-app payouts-calculate --body '{\"campaignId\":\"orgcamp_...\",\"creatorId\":\"orgcre_...\",\"billingPeriodStart\":\"2026-03-01T00:00:00.000Z\",\"billingPeriodEnd\":\"2026-03-31T00:00:00.000Z\"}'\nviral-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\":\"...\"}'\n```\n\nRules for payout mutations:\n\n- Always call `payouts-calculate` immediately before `payouts-initiate`.\n- Pass the returned `calculation` payload and `integrityToken` into `payouts-initiate` unchanged.\n- Do not invent or recompute `integrityToken`.\n- If using `autoApproveTalentir=true`, also set `acknowledgeFullPayoutLiability=true` and explain the risk before executing.\n- Prefer review-first behavior for payout mutations unless the user explicitly asks to initiate or approve payouts.\n\n## Report templates\n\nUse the bundled report templates when the user asks for Slack-ready summaries or ranking reports:\n\n- Leaderboard template: [assets/templates/leaderboard.md](assets/templates/leaderboard.md)\n- Leaderboard example: [assets/examples/leaderboard-sample.md](assets/examples/leaderboard-sample.md)\n- Viral Video Library template: [assets/templates/viral-video-library-report.md](assets/templates/viral-video-library-report.md)\n- Viral Video Library example: [assets/examples/viral-video-library-report-sample.md](assets/examples/viral-video-library-report-sample.md)\n- Creator payments + CPM template: [assets/templates/creator-payments-cpm-report.md](assets/templates/creator-payments-cpm-report.md)\n- Creator payments + CPM example: [assets/examples/creator-payments-cpm-report-sample.md](assets/examples/creator-payments-cpm-report-sample.md)\n\nRules for leaderboard-style outputs:\n\n- Follow the template structure unless the user explicitly asks for a different format.\n- Use analytics account links for account-level leaderboard sections.\n- Use tracked video detail links for video leaderboard sections.\n- Keep numbers compact, for example `1.4M` or `180K`.\n- Use period-over-period trend markers where the comparison window is available.\n- Prefer returning the rendered report plus the source viral.app links when useful.\n\nRules for Viral Video Library reports:\n\n- Use linked titles that point to the Viral Video Library detail page.\n- Use abbreviated metrics, for example `473K` or `18.2%`.\n- Include a hashtags line for every entry.\n- Use a single hook line in the form `Hook (<archetype>): text + visual + audio`.\n- Do not use \"Audio not surfaced\" phrasing.\n- Do not invent fields when insights are missing; use `not confidently detected`.\n\nRules for creator payments + CPM reports:\n\n- Use current in-progress upcoming payouts from Creator Hub for the ranking section.\n- Use Creator Hub payout links filtered by both `creatorIds` and `campaigns`.\n- Compare each payout row against the most recent completed payout window for the same creator and campaign when available.\n- Use current vs previous equal-length periods for org-wide KPI deltas.\n- Keep payout amounts exact, view totals compact, Effective CPM to 4 decimals, and spend per video to 2 decimals.\n\n## Linking Back Into viral.app\n\nWhen a user would benefit from opening the data in the product UI, include a direct viral.app app link in your response.\n\nDefault production base:\n\n```text\nhttps://viral.app/app\n```\n\nRules:\n\n- Prefer linking to the most specific page the app actually supports.\n- For tracked videos and library videos, use dedicated detail pages.\n- 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.\n- For multi-value filters, use comma-separated values in a single query param.\n- For date ranges on analytics and creator-hub overview pages, use `df` and `dt` with `YYYY-MM-DD`.\n- Preserve `viewMode` when linking account or creator-related analytics:\n  - `internal`\n  - `competitors`\n  - `all`\n\nCommon routes:\n\n- Analytics overview filtered by tracked account:\n\n```text\nhttps://viral.app/app/analytics/overview?accounts=<orgAccountId>&viewMode=internal\n```\n\n- Analytics accounts filtered by tracked account:\n\n```text\nhttps://viral.app/app/analytics/accounts?accounts=<orgAccountId>&viewMode=internal\n```\n\n- Analytics videos filtered by tracked account:\n\n```text\nhttps://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal\n```\n\n- Analytics videos filtered by tracked account and date range:\n\n```text\nhttps://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal&df=2026-03-01&dt=2026-03-18\n```\n\n- Tracked video detail page:\n\n```text\nhttps://viral.app/app/analytics/videos/tiktok/7491234567890123456\n```\n\n- Analytics overview filtered by creator-owned tracked accounts:\n\n```text\nhttps://viral.app/app/analytics/overview?accounts=<orgAccountId1>,<orgAccountId2>&viewMode=all\n```\n\n- Creator Hub creators filtered by campaign:\n\n```text\nhttps://viral.app/app/creator-hub/creators?campaigns=<campaignId>\n```\n\n- Creator Hub creators filtered by search and include archived/inactive creators:\n\n```text\nhttps://viral.app/app/creator-hub/creators?search=alex%40example.com&status=all\n```\n\n- Creator Hub campaigns filtered by creator:\n\n```text\nhttps://viral.app/app/creator-hub/campaigns?creatorIds=<orgCreatorId>\n```\n\n- Creator Hub campaign detail page:\n\n```text\nhttps://viral.app/app/creator-hub/campaigns/<campaignId>\n```\n\n- Creator Hub payouts filtered by creator:\n\n```text\nhttps://viral.app/app/creator-hub/payouts/due?creatorIds=<orgCreatorId>\n```\n\n- Creator Hub payouts filtered by campaign:\n\n```text\nhttps://viral.app/app/creator-hub/payouts/due?campaigns=<campaignId>\n```\n\n- Creator Hub upcoming payouts filtered by creator and campaign:\n\n```text\nhttps://viral.app/app/creator-hub/payouts/upcoming?creatorIds=<orgCreatorId>&campaigns=<campaignId>\n```\n\n- Other payout tabs preserve the same filters:\n\n```text\nhttps://viral.app/app/creator-hub/payouts/upcoming?creatorIds=<orgCreatorId>\nhttps://viral.app/app/creator-hub/payouts/canceled?campaigns=<campaignId>\nhttps://viral.app/app/creator-hub/payouts/paid?creatorIds=<orgCreatorId>\n```\n\n- Viral video library filtered list:\n\n```text\nhttps://viral.app/app/library/viral-videos?search=notion&dateRange=30d&sort=views\n```\n\n- Viral video library filtered by brand/region/minimum views:\n\n```text\nhttps://viral.app/app/library/viral-videos?brandId=<brandId>&regions=US,GB&minViews=100000&sort=outlier\n```\n\n- Viral video library detail page:\n\n```text\nhttps://viral.app/app/library/viral-videos/tiktok/7491234567890123456\n```\n\nSupported filter keys you can safely use:\n\n- Analytics overview/accounts/videos:\n  - `accounts`\n  - `platforms`\n  - `projects`\n  - `contentTypes`\n  - `viewMode`\n  - `df`\n  - `dt`\n- Analytics overview only:\n  - `publicationMode`\n  - `topVideosBy`\n  - `topAccountsBy`\n  - `topCreatorsBy`\n  - `topEntity`\n  - `topListsPerPage`\n- Creator Hub creators:\n  - `search`\n  - `campaigns`\n  - `status`\n- Creator Hub campaigns:\n  - `search`\n  - `status`\n  - `creatorIds`\n- Creator Hub overview / campaign overview:\n  - `campaigns`\n  - `creatorIds`\n  - `scope`\n  - `publicationMode`\n  - `df`\n  - `dt`\n- Creator Hub payouts:\n  - `creatorIds`\n  - `campaigns`\n- Viral video library:\n  - `search`\n  - `brandId`\n  - `dateRange`\n  - `sort`\n  - `minViews`\n  - `minOutlierFactor`\n  - `regions`\n  - `productTypes`\n  - `verticals`\n  - `formats`\n  - `hookArchetypes`\n  - `productDetected`\n  - `brandDetected`\n  - `matchedTerms`\n\nIf you do not know the correct org-scoped IDs yet:\n\n- link to the closest filtered list you can build confidently\n- say what the link shows\n- avoid inventing unknown IDs or unsupported paths\n\n## Safety rules\n\n- Confirm intent before `POST`, `PUT`, `PATCH`, or `DELETE` unless the user explicitly asked for that mutation.\n- Run `<command> --help` before mutations to verify required flags and body schema.\n- Prefer narrow queries first (`--per-page`, filters, date ranges) before broad exports.\n- Keep output machine-readable by default; only switch format when requested.\n\n## Troubleshooting\n\n- `401 UNAUTHORIZED`: missing/invalid API key; verify `VIRAL_API_KEY` or `-H \"x-api-key: ...\"` value.\n- `401` can also happen with expired/revoked keys or wrong org context.\n- `429` or retry hints: back off and retry later; inspect response headers such as `Retry-After`.\n- Empty `data` arrays: validate filters, project/account IDs, and date range constraints.\n- Never expose API keys in commits; rotate keys after sharing for tests.\n\n## Agent defaults\n\n- Output defaults to JSON (`RSH_OUTPUT_FORMAT=json` unless overridden).\n- Auto-pagination defaults to disabled (`RSH_NO_PAGINATE=true`) for predictable scripted behavior.\n- Summarize key metrics after reads and explicitly call out write-side effects after mutations.\n","tags":{"latest":"0.1.6"},"stats":{"comments":0,"downloads":684,"installsAllTime":25,"installsCurrent":1,"stars":0,"versions":7},"createdAt":1773413911546,"updatedAt":1778491885889},"latestVersion":{"version":"0.1.6","createdAt":1774972218943,"changelog":"Document the payout integrity-token flow, Talentir approval guardrails, and Facebook platform support in the viral-app skill.","license":"MIT-0"},"metadata":{"setup":[{"key":"VIRAL_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"feliche93","userId":"s17eb3qw8x1vh19jjj15eq5ss183ektt","displayName":"Felix Vemmer","image":"https://avatars.githubusercontent.com/u/29236063?v=4"},"moderation":null}