API リファレンス
GET /credits
クレジット台帳の summary と直近のイベントから、何がクレジットを動かしたかを確認する API です。
このページの内容7項目
GET /api/signal-foundry/credits は、クレジット台帳の summary と直近のイベントを返します。
このエンドポイントは「何が起きたか」を調べるために使います。今書き込みを実行できるか判断する場合は GET /credits/balance または sf credits balance --json を使います。
契約サマリー
| 項目 | 値 |
|---|---|
| Method | GET |
| Path | /api/signal-foundry/credits |
| Auth | production は API key 必須 |
| Usage | request usage に count |
| Credit | summary 確認では消費しない |
| CLI での実行 | sf credits summary --json |
| Primary question | どの meter / usage が credit event を記録したか |
リクエスト
curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/credits?days=7&limit=5" \ -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"
CLI での実行:
sf credits summary --days 7 --limit 5 --json
クエリパラメータ:
| パラメータ | 型 | 既定値 | 備考 |
|---|---|---|---|
days | integer | 30 | 1..365 |
limit | integer | 10 | summary.recentEvents[] の上限。1..100 |
レスポンス
見る key:
summary.totalQuantitysummary.used_creditssummary.remaining_creditssummary.available_creditssummary.reserved_creditssummary.lastRecordedAtsummary.periodStartsummary.periodEndsummary.meterBreakdown[]summary.meterBreakdown[].meterTypesummary.meterBreakdown[].quantitysummary.usageBreakdown[]summary.usageBreakdown[].usageKeysummary.usageBreakdown[].quantitysummary.recentEvents[]summary.recentEvents[].credit_event_idsummary.recentEvents[].meter_typesummary.recentEvents[].quantitysummary.recentEvents[].usage_keysummary.recentEvents[].リファレンス_typesummary.recentEvents[].リファレンス_idsummary.recentEvents[].recorded_atmeta.daysmeta.recent_limit
現在見えるイベント
| イベント | 意味 |
|---|---|
usage.request | data endpoint の request credit を使った |
usage.signal | credit-consuming Signal read の operation credit を使った |
reservation.reserve | 実行前に クレジットを予約した |
reservation.release | 予約済み クレジットを解放した |
summary.used_credits は対象期間の消費量で、summary.totalQuantity と同じ値です。summary.remaining_credits / summary.available_credits / summary.reserved_credits は現在の残高のスナップショットです。付与の内訳と有効期限はこのエンドポイントではなく GET /credits/balance の balance.grants[] で確認します。
エラー
| コード | ステータス | 復旧 |
|---|---|---|
invalid_query | 400 | days は 1..365、limit は 1..100 にする |
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 まで待つ |
復旧方法
直近のイベントが想定と違う場合は、billing provider ではなくクレジット台帳の問題として切り分けます。
確認順:
summary.periodStart/summary.periodEndが見たい期間を含むか確認します。summary.meterBreakdown[]でどの meter が増えたか見ます。summary.usageBreakdown[]で request / signal などの usage を見ます。summary.recentEvents[]のリファレンス_type/リファレンス_idから該当実行を辿ります。- 今実行できるかは
/creditsでは判断せず、sf credits balance --jsonに戻ります。
現時点で含めないもの
- billing provider と結びついた請求表示
- plan 変更やクレジット pack 購入 UI
- API request usage の rate limit summary