API リファレンス
GET /credits
credit ledger summary と recent events から、何が credit を動かしたか確認する API contract です。
このページの内容7項目
GET /api/signal-foundry/credits は、credit ledger の summary と recent events を返します。
この endpoint は「何が起きたか」を調べるために使います。今 write を実行できるか判断する場合は GET /credits/balance または sf credits balance --json を使います。
契約サマリー
| Field | Value |
|---|---|
| Method | GET |
| Path | /api/signal-foundry/credits |
| Auth | production は API key 必須 |
| Usage | request usage に count |
| Credit | summary 確認では消費しない |
| CLI equivalent | 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 equivalent:
sf credits summary --days 7 --limit 5 --json
クエリパラメータ:
| Param | Type | Default | Notes |
|---|---|---|---|
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[].reference_typesummary.recentEvents[].reference_idsummary.recentEvents[].recorded_atmeta.daysmeta.recent_limit
現在見えるイベント
| Event | Meaning |
|---|---|
usage.basic_company | saved List materialize や source resolve/select で Basic company credit を使った |
usage.enrichment_source | website enrichment など source enrichment credit を使った |
reservation.reserve | 実行前に credit を予約した |
reservation.release | 予約済み credit を解放した |
summary.used_credits は対象期間の消費量で、summary.totalQuantity と同じ値です。summary.remaining_credits / summary.available_credits / summary.reserved_credits は現在の残高 snapshot です。grant の内訳と expiration はこの endpoint ではなく GET /credits/balance の balance.grants[] で確認します。
エラー
| Code | Status | 復旧 |
|---|---|---|
invalid_query | 400 | days は 1..365、limit は 1..100 にする |
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 まで待つ |
復旧方法
recent events が想定と違う場合は、billing provider ではなく credit ledger の問題として切り分けます。
確認順:
summary.periodStart/summary.periodEndが見たい期間を含むか確認する。summary.meterBreakdown[]でどの meter が増えたか見る。summary.usageBreakdown[]でlist.materialize、source.resolve、source.select、list.enrichなどの usage を見る。summary.recentEvents[]のreference_type/reference_idから該当 run、source、list を辿る。- 今実行できるかは
/creditsでは判断せず、sf credits balance --jsonに戻る。
現時点で含めないもの
- billing provider と結びついた請求表示
- plan 変更や credit pack 購入 UI
- API request usage の rate limit summary