API リファレンス
GET /credits/balance
今使えるクレジットの残高を確認し、クレジットを使う書き込みを実行してよいか判断するための API の入出力です。
このページの内容5項目
GET /api/signal-foundry/credits/balance は、今使えるクレジットと付与内訳を返します。
このエンドポイントは「今実行できるか」を判断するために使います。過去に何が起きたかを確認する場合は GET /credits を使います。
契約サマリー
| 項目 | 値 |
|---|---|
| Method | GET |
| Path | /api/signal-foundry/credits/balance |
| Auth | production は API key 必須 |
| Usage | request usage としてカウントする |
| Credit | 残高確認では消費しない |
| CLI での実行 | sf credits balance --json |
| Primary question | available_credits は次の書き込みの maxCredits 以上か |
credit-consuming Signal read や繰り返し実行の前に確認する代表例:
sf search "<query>" --jsonを大量に回す前sf signals <companyId> --jsonを連続して読む前- credit-consuming Signal read が
max_credits_requiredを返した後
リクエスト
curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/credits/balance" \ -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"
CLI での実行:
sf credits balance --json
クエリパラメータはありません。API key に紐づく account の残高を返します。
レスポンス
見る key:
balance.available_creditsbalance.remaining_creditsbalance.reserved_creditsbalance.consumption_orderbalance.grants[]balance.grants[].grant_idbalance.grants[].source_typebalance.grants[].remaining_creditsbalance.grants[].reserved_creditsbalance.grants[].available_creditsbalance.grants[].expires_atmeta.auth_mode
エラー
| Code | Status | 復旧 |
|---|---|---|
invalid_query | 400 | 不要な検索条件パラメータを外す |
invalid_api_key | 401 | CLI の場合は sf login をやり直す。直接 API を呼んでいる場合は API key を rotate する |
api_key_expired / api_key_revoked | 401 | 有効な key に差し替える |
rate_limit_exceeded | 429 | Retry-After まで待つ |
復旧方法
credit_balance_insufficient が書き込みエンドポイントから返ったら、まずこのエンドポイントか sf credits balance --json を実行します。
確認順:
balance.available_creditsがmaxCreditsより小さくないか確認します。balance.grants[].expires_atで期限切れが近い付与を確認します。balance.reserved_creditsが大きい場合は、実行中の処理の完了または release を待ちます。- 何が消費したかは GET /credits で
summary.recentEvents[]を確認します。
残高不足を silent success として扱わないでください。エージェントは書き込みを止め、sf credits balance --json の結果をユーザーに見せます。