Back to Details

viral-app

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

viral-app

viral-app

Use this skill when you need to read or manage data through the viral.app API.
当你需要通过viral.app API读取或管理数据时，请使用此Skill。

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).
  • 查询分析数据（账户、视频、关键绩效指标、导出数据）。
  • 管理已追踪实体（账户、视频、排除项、刷新任务）。
  • 管理项目和创作者中心资源。
  • 获取各平台实时数据（Facebook、TikTok、Instagram、YouTube）。

Quick start

快速开始

  1. Ensure 
    viral-app
    CLI is installed and available in 
    PATH
    .
bash
viral-app --help
  1. Set API key:
bash
export VIRAL_API_KEY="..."
Get this key from viral.app dashboard at 
Settings -> API Keys
.
  1. 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.
  1. 确保
    viral-app
    CLI已安装且可在
    PATH
    中访问。
bash
viral-app --help
  1. 设置API密钥：
bash
export VIRAL_API_KEY="..."
该密钥可从viral.app控制台的
Settings -> API Keys
获取。
  1. 验证访问权限：
bash
viral-app accounts-list --per-page 1
除非已传入自定义请求头，否则包装器会自动从
VIRAL_API_KEY
注入
x-api-key
请求头。

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.
  • 任务类型：读取/报告 或 修改/管理资源。
  • 组织范围ID：
    orgacc_*
    、
    orgproj_*
    ，以及相关的创作者/活动/付款ID。
  • 平台和实体标识符（
    facebook|tiktok|instagram|youtube
    ，平台账户/视频ID）。
  • 分析任务的时间范围（
    --date-range[from]
    、
    --date-range[to]
    ）。
  • 分页/范围参数（
    --per-page
    、筛选条件）以聚焦输出内容。

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.
查看可用操作：
bash
viral-app --help
viral-app <command> --help
常见读取操作：
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
常见修改操作：
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_..."}'
付款修改流程：
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":"..."}'
付款修改规则：
  • 调用
    payouts-initiate
    前必须先调用
    payouts-calculate
    。
  • 将返回的
    calculation
    payload和
    integrityToken
    原封不动传入
    payouts-initiate
    。
  • 不要自行生成或重新计算
    integrityToken
    。
  • 如果使用
    autoApproveTalentir=true
    ，需同时设置
    acknowledgeFullPayoutLiability=true
    ，并在执行前说明相关风险。
  • 除非用户明确要求发起或批准付款，否则付款修改操作优先采用“先审核”模式。

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.
当用户需要适用于Slack的摘要或排名报告时，使用内置的报告模板：
  • 排行榜模板：assets/templates/leaderboard.md
  • 排行榜示例：assets/examples/leaderboard-sample.md
  • 热门视频库模板：assets/templates/viral-video-library-report.md
  • 热门视频库示例：assets/examples/viral-video-library-report-sample.md
  • 创作者付款+CPM模板：assets/templates/creator-payments-cpm-report.md
  • 创作者付款+CPM示例：assets/examples/creator-payments-cpm-report-sample.md
排行榜类输出规则：
  • 除非用户明确要求其他格式，否则遵循模板结构。
  • 账户级排行榜部分使用分析账户链接。
  • 视频排行榜部分使用已追踪视频详情链接。
  • 数字格式保持简洁，例如
    1.4M
    或
    180K
    。
  • 当有对比窗口时，使用同期环比趋势标记。
  • 如有帮助，优先返回渲染后的报告及对应的viral.app链接。
热门视频库报告规则：
  • 使用指向热门视频库详情页的链接标题。
  • 使用简化指标，例如
    473K
    或
    18.2%
    。
  • 每个条目都包含标签行。
  • 使用统一的钩子格式：
    Hook (<archetype>): text + visual + audio
    。
  • 不要使用“未识别音频”表述。
  • 当缺少洞察信息时，不要自行添加字段，使用
    not confidently detected
    。
创作者付款+CPM报告规则：
  • 排名部分使用创作者中心当前待处理的即将付款数据。
  • 使用按
    creatorIds
    和
    campaigns
    筛选的创作者中心付款链接。
  • 当有可用数据时，将每一行付款数据与同一创作者和活动的最近完成付款周期进行对比。
  • 组织级关键绩效指标差值使用当前周期与之前等长周期进行对比。
  • 付款金额保持精确，总计金额格式简洁，有效CPM保留4位小数，单视频支出保留2位小数。

Linking Back Into viral.app

跳转至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
当用户需要在产品UI中查看数据时，请在回复中包含直接的viral.app应用链接。
默认生产环境基础地址：
text
https://viral.app/app
规则：
  • 优先链接到应用实际支持的最具体页面。
  • 对于已追踪视频和库视频，使用专属详情页。
  • 对于账户和创作者，优先使用筛选后的列表/仪表盘视图。目前应用暂未提供专属的账户详情页或创作者详情页路由。
  • 多值筛选条件使用单个查询参数，值用逗号分隔。
  • 分析页面和创作者中心概览页面的日期范围使用
    df
    和
    dt
    参数，格式为
    YYYY-MM-DD
    。
  • 链接账户或创作者相关分析页面时保留
    viewMode
    参数： 
    • internal
    • competitors
    • all
常见路由：
  • 按已追踪账户筛选的分析概览：
text
https://viral.app/app/analytics/overview?accounts=<orgAccountId>&viewMode=internal
  • 按已追踪账户筛选的分析账户页面：
text
https://viral.app/app/analytics/accounts?accounts=<orgAccountId>&viewMode=internal
  • 按已追踪账户筛选的分析视频页面：
text
https://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal
  • 按已追踪账户和日期范围筛选的分析视频页面：
text
https://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal&df=2026-03-01&dt=2026-03-18
  • 已追踪视频详情页：
text
https://viral.app/app/analytics/videos/tiktok/7491234567890123456
  • 按创作者拥有的已追踪账户筛选的分析概览：
text
https://viral.app/app/analytics/overview?accounts=<orgAccountId1>,<orgAccountId2>&viewMode=all
  • 按活动筛选的创作者中心创作者页面：
text
https://viral.app/app/creator-hub/creators?campaigns=<campaignId>
  • 按搜索关键词筛选并包含已归档/非活跃创作者的创作者中心创作者页面：
text
https://viral.app/app/creator-hub/creators?search=alex%40example.com&status=all
  • 按创作者筛选的创作者中心活动页面：
text
https://viral.app/app/creator-hub/campaigns?creatorIds=<orgCreatorId>
  • 创作者中心活动详情页：
text
https://viral.app/app/creator-hub/campaigns/<campaignId>
  • 按创作者筛选的创作者中心待付款页面：
text
https://viral.app/app/creator-hub/payouts/due?creatorIds=<orgCreatorId>
  • 按活动筛选的创作者中心待付款页面：
text
https://viral.app/app/creator-hub/payouts/due?campaigns=<campaignId>
  • 按创作者和活动筛选的创作者中心即将付款页面：
text
https://viral.app/app/creator-hub/payouts/upcoming?creatorIds=<orgCreatorId>&campaigns=<campaignId>
  • 其他付款标签页保留相同筛选条件：
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>
  • 筛选后的热门视频库列表：
text
https://viral.app/app/library/viral-videos?search=notion&dateRange=30d&sort=views
  • 按品牌/地区/最低播放量筛选的热门视频库：
text
https://viral.app/app/library/viral-videos?brandId=<brandId>&regions=US,GB&minViews=100000&sort=outlier
  • 热门视频库详情页：
text
https://viral.app/app/library/viral-videos/tiktok/7491234567890123456
可安全使用的筛选键：
  • 分析概览/账户/视频： 
    • accounts
    • platforms
    • projects
    • contentTypes
    • viewMode
    • df
    • dt
  • 仅分析概览： 
    • publicationMode
    • topVideosBy
    • topAccountsBy
    • topCreatorsBy
    • topEntity
    • topListsPerPage
  • 创作者中心创作者： 
    • search
    • campaigns
    • status
  • 创作者中心活动： 
    • search
    • status
    • creatorIds
  • 创作者中心概览/活动概览： 
    • campaigns
    • creatorIds
    • scope
    • publicationMode
    • df
    • dt
  • 创作者中心付款： 
    • creatorIds
    • campaigns
  • 热门视频库： 
    • search
    • brandId
    • dateRange
    • sort
    • minViews
    • minOutlierFactor
    • regions
    • productTypes
    • verticals
    • formats
    • hookArchetypes
    • productDetected
    • brandDetected
    • matchedTerms
如果不知道正确的组织范围ID：
  • 链接到你能确定构建的最接近的筛选列表页面
  • 说明该链接展示的内容
  • 不要编造未知ID或使用不支持的路径

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.
  • 执行
    POST
    、
    PUT
    、
    PATCH
    或
    DELETE
    操作前需确认用户意图，除非用户明确要求执行该修改操作。
  • 执行修改操作前运行
    <command> --help
    以验证所需参数和请求体结构。
  • 优先执行范围较窄的查询（
    --per-page
    、筛选条件、日期范围），再进行大范围导出。
  • 默认输出机器可读格式；仅在用户要求时切换格式。

Troubleshooting

故障排除

  • 401 UNAUTHORIZED
    : missing/invalid API key; verify 
    VIRAL_API_KEY
    or 
    -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.
  • 401 UNAUTHORIZED
    ：缺少/无效API密钥；验证
    VIRAL_API_KEY
    或
    -H "x-api-key: ..."
    的值。
  • 401
    错误也可能由密钥过期/撤销或组织上下文错误导致。
  • 429
    或重试提示：暂停后重试；查看响应头如
    Retry-After
    。
  • 空
    data
    数组：验证筛选条件、项目/账户ID以及日期范围约束。
  • 切勿在提交的代码中暴露API密钥；测试分享后需轮换密钥。

Agent defaults

Agent默认设置

  • 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.
  • 输出默认为JSON格式（
    RSH_OUTPUT_FORMAT=json
    ，除非被覆盖）。
  • 默认禁用自动分页（
    RSH_NO_PAGINATE=true
    ）以实现可预测的脚本行为。
  • 读取操作后汇总关键指标，修改操作后明确说明写入侧影响。