API リファレンス

GET /credits/balance

今 credit-consuming write を実行できるか確認する balance contract です。

このページの内容5項目

GET /api/signal-foundry/credits/balance は、今使える credit と grant breakdown を返します。

この 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` は次の write の `maxCredits` 以上か

credit-consuming write の前に確認する代表例:

sf list materialize --execute --max-credits <n> --json
sf list enrich <listId> --source website --execute --max-credits <n> --json
sf source resolve <sourceId> --execute --max-credits <n> --json
sf source select <sourceId> --row <sourceRowId> --company <companyId> --max-credits 1 --json

リクエスト

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_credits
balance.remaining_credits
balance.reserved_credits
balance.consumption_order
balance.grants[]
balance.grants[].grant_id
balance.grants[].source_type
balance.grants[].remaining_credits
balance.grants[].reserved_credits
balance.grants[].available_credits
balance.grants[].expires_at
meta.auth_mode

エラー

Code	Status	復旧
`invalid_query`	400	不要な query parameter を外す
`invalid_api_key`	401	API key を再発行し、CLI なら `sf auth setup` をやり直す
`api_key_expired` / `api_key_revoked`	401	active key に差し替える
`rate_limit_exceeded`	429	`Retry-After` まで待つ

復旧方法

credit_balance_insufficient が write endpoint から返ったら、まずこの endpoint か sf credits balance --json を実行します。

確認順:

balance.available_credits が maxCredits より小さくないか見る。
balance.grants[].expires_at で期限切れが近い grant を確認する。
balance.reserved_credits が大きい場合は、実行中 run の完了または release を待つ。
何が消費したかは GET /credits で summary.recentEvents[] を見る。

残高不足を silent success として扱わないでください。agent は write を止め、sf credits balance --json の結果をユーザーに見せます。

契約サマリー

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 は次の write の maxCredits 以上か

credit-consuming write の前に確認する代表例:

sf list materialize --execute --max-credits <n> --json

sf list enrich <listId> --source website --execute --max-credits <n> --json

sf source resolve <sourceId> --execute --max-credits <n> --json

sf source select <sourceId> --row <sourceRowId> --company <companyId> --max-credits 1 --json

レスポンス

見る key:

balance.available_credits

balance.remaining_credits

balance.reserved_credits

balance.consumption_order

balance.grants[]

balance.grants[].grant_id

balance.grants[].source_type

balance.grants[].remaining_credits

balance.grants[].reserved_credits

balance.grants[].available_credits

balance.grants[].expires_at

meta.auth_mode

Code

Status

復旧

invalid_query

400

不要な query parameter を外す

invalid_api_key

401

API key を再発行し、CLI なら sf auth setup をやり直す

api_key_expired / api_key_revoked

401

active key に差し替える

rate_limit_exceeded

429

Retry-After まで待つ

復旧方法

credit_balance_insufficient が write endpoint から返ったら、まずこの endpoint か sf credits balance --json を実行します。

確認順:

balance.available_credits が maxCredits より小さくないか見る。

balance.grants[].expires_at で期限切れが近い grant を確認する。

balance.reserved_credits が大きい場合は、実行中 run の完了または release を待つ。

何が消費したかは GET /credits で summary.recentEvents[] を見る。

残高不足を silent success として扱わないでください。agent は write を止め、sf credits balance --json の結果をユーザーに見せます。