クレジット表
Signal Foundry の利用量計測の 3 層と、操作ごとのクレジット消費、無料境界、再試行ルールを固定します。
このページの内容9項目
このページは、Signal Foundry の利用量計測とクレジット入出力の正本です。
クレジットは、データ取得の request と credit-consuming Signal read の両方を台帳(ledger)で扱います。Signal Foundry の Company-first data endpoint を API / CLI から読むと Request Credit、一部の signal read では追加の Signal Credit を使います。
まず見る command
sf credits balance --json sf credits summary --json sf usage --json sf query --file company-query.json --json
見る key:
balance.available_creditsbalance.remaining_creditsbalance.reserved_creditsbalance.grants[]summary.used_creditssummary.meterBreakdown[]summary.usageBreakdown[]usage_limits.remainingusage_limits.limits.planquery.executors.financial_gold.statusquery.executors.financial_gold.result.matched_countcompanies[].company.company_idwarnings[]meta.coverage_warningsmeta.returned_companies
credits balance は「今実行できるか」を見ます。credits summary は「何が credit event を作ったか」を見ます。 財務しきい値は自然文 q に残さず、company_query.v1 を作って sf query --file company-query.json --json で実行します。
利用量計測の 3 層
利用量の計測は 3 層に分かれます。同じ「使いすぎ」でも、見る場所と復旧手順が違います。
| 計測 | 何を見るか | 主な用途 |
|---|---|---|
| API usage summary | request count、endpoint、response bytes | API key の利用状況、rate limit の調整 |
| Plan quota | search / card / credit-consuming Signal read の残りと quota error の reset_at | daily_* / monthly_* quota error の復旧 |
| クレジット台帳 | Request Credit / Signal Credit の消費、付与、reservation | 使えるクレジット残高と消費履歴の確認 |
API usage summary は、API キー設定画面で確認できる 30 日の breakdown です。「どの API key がどれだけ使われたか」を見るためのもので、plan quota の残り、credit 残高、請求額そのものではありません。
Plan quota は sf usage --json、クレジット台帳は sf credits balance --json と sf credits summary --json で確認します。
Stripe subscription / order は付与を作る入口です。実際のプロダクト利用可否は sf_credit_grants と消費記録で判断します。
Request Credit と Signal Credit の境界
Company-first API は、顧客に見える利用単位を Request Credit と Signal Credit に分けます。
| Credit boundary | 例 |
|---|---|
| Request Credit | Search、Company Card、Usage、cached Signal read |
| Signal Credit | credit-consuming Signal read、対応している場合の evidence 抽出 |
credits、usage などの確認・管理 endpoint は request credit の対象外です。
Plan と quota
plan の価格、quota、rate limit、plan ごとのクレジット付与は 請求 を正本にします。
契約とクレジット付与の単位はチームワークスペースです。1 人で使う場合も、owner だけのチームワークスペースが API key、usage、billing の範囲になります。個人向け checkout は通常導線にしません。
Credit Pack は credit 残高だけを増やし、plan quota、RPM、検索結果上限は増やしません(請求 を見ます)。
操作ごとのクレジット
| Operation | Request Credit | Signal Credit | CLI |
|---|---|---|---|
search | 1 | 0 | sf search 7203 --json |
Company Card | 1 | 0 | sf company jpx_7203 --json |
Signals: cases | 1 | credit-consuming signal read として使う場合 1 | sf signals jpx_6836 --json |
Signals: observations | 1 | 0 | sf signals jpx_7203 --json |
Signals: IR | 1 | IR evidence として使う場合 1 | sf signals jpx_7203 --json |
query | 実行可能な検索が走る場合 1 | 0 | sf query --file company-query.json --json |
| 根拠の確認 | 1 | 0 | Company Card と company-level signals を読む |
job search | 1 | 0 | sf job search "<query>" --json |
construction search | 1 | 0 | sf construction search "<query>" --json |
| credit-consuming Signal read | 1 | signal 単位 | sf usage --json と sf credits summary --json で利用量を確認 |
credits balance / credits summary / usage | 0 | 0 | sf credits balance --json |
実行前の確認
credit-consuming Signal read や大きい利用量の前に、残高と直近利用を確認します。
sf credits balance --json sf credits summary --json sf credits summary --days 7 --limit 5 --json sf usage --json
通常探索では、エージェントが sf search の JSON からローカルリストや CSV を作れます。再利用する会社群は、確定した company_id を sf list でサーバー側の Saved List に保存できます。Search や Company Card を繰り返し読む前に、実行時の sf usage --json と sf credits balance --json を確認してください。
再試行と Idempotency
同じ書き込みを再試行する場合は idempotency を使います。
| Surface | 必須か | 補足 |
|---|---|---|
| CLI | 同じコマンドの再実行で安全に再試行する(専用フラグはない) | 失敗時は error.suggested_next_commands を見る |
| HTTP API | Idempotency-Key header(opt-in) | credit を消費する POST endpoint で使う |
同じ会社 / signal / idempotency key の再試行では二重消費しません。対象、上限、idempotency key を変える場合は別実行として扱います。
復旧方法
| Error | 次に見る command | 復旧 |
|---|---|---|
max_credits_required | sf <command> --help | 上限指定つきの課金実行の契約。CLI に上限フラグは現在ないため、error.hint に従う |
max_credits_exceeded | sf search "<query>" --json | 検索条件や対象会社数を絞る |
credit_balance_insufficient | sf credits balance --json | 付与残高を確認する |
daily_search_quota_exceeded / monthly_search_quota_exceeded | sf usage --json | reset_at を待つ、条件を絞る、Free なら Pro の月次 quota を使う |
daily_card_quota_exceeded / monthly_card_quota_exceeded | sf usage --json | reset_at を待つ、読む会社を絞る、Free なら Pro の月次 quota を使う |
daily_deep_signal_quota_exceeded / monthly_deep_signal_quota_exceeded | sf usage --json | signal read の対象を絞るか reset_at を待つ |
account_scope_conflict | sf auth show --json | API key のチームワークスペース範囲に任せ、request 側の account 指定を外す |
unsupported / weak / needs_human が返る場合は、クレジットを使う実行へ進みません。条件を分解して人間に確認してください。
次に読むページ
- plan と quota の正本: 請求
- クレジット台帳 API: GET /credits/balance