Skip to main content
Chartmetric連携は、自分で用意したChartmetric Developer APIの契約と refresh tokenを使うBYOK（Bring Your Own Key）方式です。 QAIPが共有APIキーを提供したり、対応外のプランを従量課金へ自動で 切り替えたりすることはありません。

​
利用できるか確認する

シークレット作成画面でChartmetricを選ぶと、その環境で認証済みの 契約プランだけが表示されます。自分のプランが表示されない場合は 登録できません。契約内容はChartmetricの管理画面で確認してください。
Agentの利用は、自分のChartmetric契約のquota、rate limit、費用を 消費することがあります。複数のAgentや実行を並行すると、その分だけ API requestが増える可能性があります。

​
Refresh tokenを登録する

  1. ChartmetricでDeveloper API用のrefresh tokenを取得します。
  2. ダッシュボードの「シークレット」を開きます。
  3. 「新規シークレット作成」を選び、データソースタイプを 「Chartmetric」にします。
  4. シークレット名とrefresh tokenを入力します。
  5. 画面に表示された自分の契約プランを選び、 chartmetric-byoc-v1のLLM provider/subprocessor/region、 履歴・log・traceの保持日数、ユーザー・管理者の削除経路を確認します。
  6. 全Agentで既定有効、quota・費用、LLM処理、会話履歴保存、 保持・削除に関する5項目を個別に確認して保存します。
登録できるChartmetricシークレットは1ユーザーにつき1件です。 登録処理ではChartmetric APIを呼び出しません。refresh tokenは保存後に 再表示されず、Agentが実際にツールを使うときだけ認証に利用されます。
データの送信先、履歴の保持期間、削除経路は登録画面に表示される データ利用プロファイルと、契約ownerが管理する運用記録を確認してください。 profile変更時の再確認と公開判断は運用で管理され、登録済み同意と 現行profileのhashはapplicationでは照合しません。

​
6つのツールを使う

登録後、既存と新規のAgentで次の6つのツールが既定で有効になります。 検索候補が複数ある場合、Agentは先頭候補を自動採用しません。 名前、アーティスト、ISRCなどを見比べて対象を指定してください。

​
対応する指標を指定する

アーティスト推移では、次のsourceとmetricを利用できます。 アーティスト楽曲の並べ替えはspotify_plays、tiktok_posts、 youtube_views、shazam_count、spotify_popularity、scoreに対応します。 楽曲統計はSpotify、TikTok、Chartmetric、YouTube、Shazam、Genius、 SoundCloudに対応します。明示できるmetricはSpotifyのpopularity / streams、TikTokのposts / views / comments / sound_*、 Chartmetricのscore / rankです。 契約プランまたはツールが対応しないendpoint・metricはエラーになります。 QAIPは別のmetric、Web検索、Xなどの値をChartmetricの値として補完しません。 rankは小さい値ほど上位です。TikTokのpostsとviewsも別の指標として扱います。

​
日付とページを明示する

アーティスト推移にはsinceとuntilをYYYY-MM-DDで両方指定します。 楽曲統計の日付は両方指定するか、両方省略します。片側だけの指定や 開始日が終了日より後の指定は受け付けません。 検索はアーティスト5件、楽曲10件、アーティスト楽曲は50件が既定です。 いずれも1回に1ページだけ取得し、自動で次ページへ進んだり、期間を 分割したりしません。続きが必要なときは、回答に示されたpaginationを 確認して次のoffsetを指定してください。検索結果のhas_moreをproviderが 返さない場合は、上限件数に達したことをwarningとして示します。

​
引用とグラフを確認する

引用を有効にしたAgentでは、検証済みのChartmetric artist IDまたはtrack IDから 作ったChartmetric公式画面へのリンクが回答に付きます。引用を無効にした場合や、 安全なIDを確認できない場合はリンクを作りません。 推移データは回答の分析用データを変えず、表示だけを最大50点にサンプリングする ことがあります。その場合は入力点数と表示点数が注記されます。 Redaction policyによって名前を安全に送れない場合、Agentは元の名前へ フォールバックしません。Chartmetric ID、ISRC、またはSpotify、Apple Music、 YouTube Musicなどの対応DSP URLを指定してください。

​
無効化・更新・削除する

1つのAgentだけで止めるには、Agent編集画面の「ツール」で 「Chartmetricの検索・分析ツールを使う」をオフにして保存します。 他のAgentの設定は変わりません。 refresh tokenを変更するには、シークレット一覧から登録済みのChartmetricを 編集します。tokenの更新だけでは、現在の契約プランとデータ利用への同意は 変更されません。データ利用プロファイルが更新された場合や、削除後に 作り直す場合は再同意が必要です。 削除はシークレット一覧から行います。処理中はpending状態が表示されることが あり、その間は新しいAgent実行でChartmetricツールを利用できません。 削除されたシークレットには7日間の復旧期間がありますが、QAIP上では 削除済みの同意を新しい登録へ流用しません。
環境がdormant状態の場合は、新規登録とAgentでの有効化を受け付けません。 tokenを再登録せず、Chartmetricの利用再開を待ってください。既存登録の無効化・更新・削除は続けられます。

​
エラーから復旧する

同じAgent実行ではChartmetricのツール呼び出しを最大10回、データ取得を retry込みで最大10回、token交換を最大2回に制限します。この上限は、 誤った繰り返しや障害時にquotaを使い続けないための安全策です。