viral-app

viral-app

viral.app API を通じてデータを読み取ったり管理したりする必要がある場合に、このスキルを使用します。

使用する場面

• 分析データ（アカウント、動画、KPI、エクスポート）を照会する場合。
• 追跡対象のエンティティ（アカウント、動画、除外設定、更新実行）を管理する場合。
• プロジェクトや Creator Hub のリソースを管理する場合。
• プラットフォームの最新データ（Facebook、TikTok、Instagram、YouTube）を取得する場合。

クイックスタート

1. viral-app CLI がインストールされ、PATH から利用できることを確認します。

viral-app --help

2. API キーを設定します。

export VIRAL_API_KEY="..."

このキーは viral.app ダッシュボードの Settings -> API Keys から取得します。

3. アクセスを確認します。

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

ラッパーは、ヘッダーがすでに渡されていない場合、VIRAL_API_KEY から x-api-key を自動的に挿入します。

事前に収集する入力情報

• タスクの種類：読み取り／レポート作成、またはリソースの変更／管理。
• 組織スコープの ID：orgacc_*、orgproj_*、該当する場合は creator／campaign／payout ID。
• プラットフォームとエンティティ識別子（facebook|tiktok|instagram|youtube、プラットフォームのアカウント ID／動画 ID）。
• 分析タスクでは期間（--date-range[from]、--date-range[to]）。
• 出力を絞り込むためのページネーション／スコープ（--per-page、フィルター）。

コマンド集

利用可能な操作を確認します。

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

一般的な読み取り操作：

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

一般的な変更操作：

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_..."}'

支払い変更の流れ：

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 ペイロードと integrityToken を変更せずに payouts-initiate に渡します。
• integrityToken を作り出したり、再計算したりしないでください。
• autoApproveTalentir=true を使用する場合は、acknowledgeFullPayoutLiability=true も設定し、実行前にリスクを説明します。
• ユーザーが支払いの開始または承認を明示的に求めない限り、支払い変更ではレビューを先に行うことを優先します。

レポートテンプレート

Slack にそのまま使える要約やランキングレポートをユーザーが求めた場合は、同梱のレポートテンプレートを使用します。

• リーダーボードテンプレート：assets/templates/leaderboard.md
• リーダーボードの例：assets/examples/leaderboard-sample.md
• Viral Video Library テンプレート：assets/templates/viral-video-library-report.md
• Viral Video Library の例：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 の参照元リンクを併せて返すことを優先します。

Viral Video Library レポートのルール：

• Viral Video Library の詳細ページを指すリンク付きタイトルを使用します。
• 473K や 18.2% のように、指標は短縮表記にします。
• 各エントリにハッシュタグ行を含めます。
• Hook (<archetype>): text + visual + audio の形式で、フックの行は1つだけ使用します。
• 「Audio not surfaced」という表現は使用しないでください。
• インサイトが不足している場合、フィールドを作り出さず、not confidently detected を使用します。

クリエイター支払い＋CPM レポートのルール：

• ランキングセクションには、Creator Hub の現在進行中または今後予定されている支払いを使用します。
• creatorIds と campaigns の両方で絞り込んだ Creator Hub の支払いリンクを使用します。
• 可能な場合、各支払い行を同じクリエイターとキャンペーンの直近の完了済み支払い期間と比較します。
• 組織全体の KPI の差分には、現在と前回で長さが等しい期間を使用します。
• 支払い金額は正確に、合計視聴回数はコンパクトに、Effective CPM は小数点以下4桁で、動画あたりの支出は小数点以下2桁で表記します。

viral.app へのリンク

ユーザーがプロダクトの UI でデータを開くと便利な場合は、回答に viral.app アプリへの直接リンクを含めてください。

本番環境のデフォルトのベース URL：

https://viral.app/app

ルール：

• アプリが実際にサポートするページのうち、最も具体的なページへのリンクを優先してください。
• トラッキング対象の動画とライブラリ内の動画には、専用の詳細ページを使用してください。
• アカウントとクリエイターには、フィルター済みのリスト／ダッシュボードビューを優先してください。現在、アプリには専用のアカウント詳細ページやクリエイター詳細ページのルートはありません。
• 複数値のフィルターでは、1 つのクエリパラメーター内で値をカンマ区切りにしてください。
• 分析ページとクリエイターハブの概要ページで期間を指定する場合は、df と dt に YYYY-MM-DD を使用してください。
• アカウントまたはクリエイター関連の分析にリンクする場合は、viewMode を維持してください：
  • internal
  • competitors
  • all

一般的なルート：

• トラッキング対象のアカウントで絞り込んだ分析概要：

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

• トラッキング対象のアカウントで絞り込んだ分析アカウント：

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

• トラッキング対象のアカウントで絞り込んだ分析動画：

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

• トラッキング対象のアカウントと期間で絞り込んだ分析動画：

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

• トラッキング対象の動画の詳細ページ：

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

• クリエイター所有のトラッキング対象アカウントで絞り込んだ分析概要：

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

• キャンペーンで絞り込んだクリエイターハブのクリエイター：

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

• 検索で絞り込み、アーカイブ済み／非アクティブのクリエイターを含めたクリエイターハブのクリエイター：

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

• クリエイターで絞り込んだクリエイターハブのキャンペーン：

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

• クリエイターハブのキャンペーン詳細ページ：

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

• クリエイターで絞り込んだクリエイターハブの支払い：

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

• キャンペーンで絞り込んだクリエイターハブの支払い：

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

• クリエイターとキャンペーンで絞り込んだクリエイターハブの今後の支払い：

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

• その他の支払いタブでも同じフィルターを維持します：

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>

• 絞り込み済みのバイラル動画ライブラリ一覧：

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

• ブランド／地域／最低再生数で絞り込んだバイラル動画ライブラリ：

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

• バイラル動画ライブラリの詳細ページ：

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 やサポートされていないパスを捏造しないでください

安全性に関するルール

• ユーザーがその変更を明示的に依頼していない限り、POST、PUT、PATCH、DELETE の前に意図を確認してください。
• 変更を行う前に <command> --help を実行し、必須フラグと本文のスキーマを確認してください。
• 大規模なエクスポートの前に、絞り込み（--per-page、フィルター、期間指定など）を使った狭い範囲のクエリを優先してください。
• 特に指定がない限り、出力は機械可読な形式にしてください。形式を変更するのは、ユーザーから依頼された場合に限ります。

トラブルシューティング

• 401 UNAUTHORIZED：API キーがないか無効です。VIRAL_API_KEY または -H "x-api-key: ..." の値を確認してください。
• キーの期限切れ／失効や、組織コンテキストの誤りでも 401 が発生することがあります。
• 429 または再試行のヒントがある場合：しばらく待ってから再試行し、Retry-After などのレスポンスヘッダーを確認してください。
• data 配列が空の場合：フィルター、プロジェクト／アカウント ID、期間の制約を確認してください。
• API キーをコミットに含めないでください。テストのために共有した後はキーをローテーションしてください。

エージェントのデフォルト設定

• 出力形式はデフォルトで JSON です（上書きされない限り、RSH_OUTPUT_FORMAT=json）。
• 予測可能なスクリプト動作のため、自動ページネーションはデフォルトで無効です（RSH_NO_PAGINATE=true）。
• 読み取り後に主要な指標を要約し、変更後には書き込みによる副作用を明示します。