API リファレンス
GET /credits/balance
今 クレジットを使う書き込みを実行できるか確認する balance 入出力 です。
このページの内容5項目
GET /api/signal-foundry/credits/balance は、今使えるクレジットと 付与内訳 を返します。
この endpoint は「今実行できるか」を判断するために使います。過去に何が起きたかを確認する場合は GET /credits を使います。
契約サマリー
| Field | Value |
|---|---|
| Method | GET |
| Path | /api/signal-foundry/credits/balance |
| Auth | production は API key 必須 |
| Usage | request usage に count |
| Credit | 残高確認では消費しない |
| CLI equivalent | sf credits balance --json |
| Primary question | available_credits は次の 書き込み の maxCredits 以上か |
深い signal や繰り返し実行の前に確認する代表例:
sf company search "<query>" --jsonを大量に回す前sf company cases <companyId> --json/observations/filingsを連続して読む前- bulk / deep signal 系 command が
max_credits_requiredを返した後
リクエスト
curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/credits/balance" \ -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"
CLI equivalent:
sf credits balance --json
クエリパラメータはありません。API key に紐づく account の balance を返します。
レスポンス
見る 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 | 不要な 検索条件 parameter を外す |
invalid_api_key | 401 | CLI なら sf login をやり直す。直接 API連携 なら API key を rotate する |
api_key_expired / api_key_revoked | 401 | active key に差し替える |
rate_limit_exceeded | 429 | Retry-After まで待つ |
復旧方法
credit_balance_insufficient が 書き込み endpoint から返ったら、まずこの endpoint か 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 の結果をユーザーに見せます。