Usage & Activity

プログラマティックな使用量レポートと、ダッシュボードの使用量・アクティビティを取得します。すべて本人のアカウントのデータのみ返します。

以下のプログラマティックレポートを除き、このページのエンドポイントはログインセッション（JWT）で認証され、常に本人のアカウントに範囲が限定されます — ダッシュボードの認証です。すべてのレスポンスの cost_krw は実際に課金されたクレジットであり、マークアップなどの内部項目は公開されません。

プログラマティックレポート#

GET/v1/usage/report

アカウントの全使用量を 1 つの軸（モデル · プロバイダー · API キー · 日付）で集計して返します。社内モニタリング・レポーティングの自動化向けの read-only API で、項目は cost_krw の降順に並びます。

このエンドポイントだけは JWT ではなく、usage:read スコープを持つ plm_ API キーで認証します（Authorization: Bearer plm_...）。スコープのないキーには 403 が返されます。usage:read のみのキーはモデル呼び出し（課金）を拒否されるため、支出権限なしでレポーティングを安全に委任できます — キーの IP allowlist も通常どおり適用されます。

パラメータ	型	必須	説明
group_by	string	任意	`model` \| `provider` \| `api_key` \| `day`。デフォルト値 `model`。
days	integer	任意	集計期間（日）。1 〜 365、デフォルト値 30。

request

curl "https://apirouter.pleum.ai/v1/usage/report?group_by=model&days=30" \
  -H "Authorization: Bearer plm_..."

200 OK

{
  "group_by": "model",
  "days": 30,
  "items": [
    {
      "key": "gpt-4o",
      "cost_krw": 48200,
      "input_tokens": 8120000,
      "output_tokens": 912000,
      "calls": 1420
    },
    {
      "key": "claude-sonnet-4-6",
      "cost_krw": 31900,
      "input_tokens": 4210000,
      "output_tokens": 640000,
      "calls": 610
    }
  ]
}

key は group_by 軸の値（モデル ID、プロバイダー ID、API キー ID、日付）です。集計範囲はキー所有者アカウントの全使用量であり、そのキーで行った呼び出しだけではありません。

使用量サマリー#

GET/v1/usage/summary

直近 24 時間の合計（calls_24h · cost_24h_krw）、直近 7 日間の日別推移（cost_by_day）、直近 30 日間の上位 5 モデル（cost_by_model）を一度に返します。

200 OK

{
  "calls_24h": 142,
  "cost_24h_krw": 3870,
  "cost_by_day": [
    {"date": "2026-06-26", "cost_krw": 1200, "calls": 40}
  ],
  "cost_by_model": [
    {"model": "gpt-4o", "cost_krw": 2600, "calls": 88}
  ]
}

呼び出しログ#

GET/v1/usage/requests

個々の呼び出し履歴をページ単位で返します。各項目にはトークン使用量、 cost_krw（課金額）、BYOK のフラグと手数料、レイテンシ、ステータスコード、エラーメッセージが含まれます。

パラメータ	型	必須	説明
period	string	任意	`1d` \| `7d` \| `30d` \| `90d`。省略時は全期間。
model	string	任意	特定のモデル ID で完全一致フィルタ。
outcome	string	任意	`success` \| `error`。結果でフィルタ。
page	integer	任意	1 以上。デフォルト値 1。
size	integer	任意	1 〜 100。デフォルト値 30。

200 OK

{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "request_id": "req_5f8e...",
      "model": "gpt-4o",
      "provider": "openai",
      "input_tokens": 1240,
      "output_tokens": 312,
      "total_tokens": 1552,
      "cache_read_tokens": 1024,
      "cost_krw": 58,
      "is_byok": false,
      "byok_fee_krw": 0,
      "latency_ms": 1841,
      "status_code": 200,
      "error_message": null,
      "created_at": "2026-06-26T08:14:02Z"
    }
  ],
  "total": 142,
  "page": 1,
  "size": 30
}

意図分布#

GET/v1/usage/classifications

Smart Mode が分類したリクエストの意図の分布を返します。件数のみを集計し、プロンプト本文は保存も公開もしません。カテゴリは vision・code・translation・creative・reasoning・general です。

パラメータ	型	必須	説明
period	string	任意	`1d` \| `7d` \| `30d` \| `90d`。省略時は全期間。

200 OK

{
  "items": [
    {"category": "code", "count": 42},
    {"category": "reasoning", "count": 17},
    {"category": "general", "count": 9}
  ],
  "total": 68
}

Smart Mode のデータが蓄積されるまでは items が空の場合があります。

アクティビティログ#

GET/v1/usage/audit-log

直近のセキュリティ・アクティビティイベント（API キー発行、管理キー発行など）を返します。各イベントには event_type、severity、resource_type、detail が含まれます。

パラメータ	型	必須	説明
limit	integer	任意	返すイベント数。デフォルト値 50、最大 200。

200 OK

{
  "events": [
    {
      "id": "e7d6...",
      "event_type": "key_created",
      "severity": "info",
      "resource_type": "api_key",
      "detail": "Created key \"prod-server\"",
      "created_at": "2026-06-26T07:55:11Z"
    },
    {
      "id": "f1a2...",
      "event_type": "management_key_created",
      "severity": "info",
      "resource_type": "management_key",
      "detail": "Created management key",
      "created_at": "2026-06-25T22:03:40Z"
    }
  ]
}