Usage & Activity

Programmatic usage reports plus your dashboard usage and activity. Everything is scoped to your own account.

Except for the programmatic report below, the endpoints on this page authenticate with your logged-in session (JWT) and are always scoped to your own account — this is the dashboard auth. In every response, cost_krw is the amount actually billed in credits; margin and other internal figures are not exposed.

Programmatic report#

GET/v1/usage/report

Returns your account's entire usage aggregated along one axis (model, provider, API key, or day). It is a read-only API for automating internal monitoring and reporting; items are sorted by cost_krw descending.

This endpoint alone authenticates not with a JWT but with a plm_ API key carrying the usage:read scope (Authorization: Bearer plm_...). Keys without the scope get a 403. A key with only usage:readis refused for model calls (billing), so you can safely delegate reporting without spend permission — the key's IP allowlist is enforced as usual.

Parameter	Type	Required	Description
group_by	string	Optional	`model` \| `provider` \| `api_key` \| `day`. Default `model`.
days	integer	Optional	Aggregation window in days. 1 to 365, default 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 is the value along the group_by axis (model ID, provider ID, API key ID, or date). The aggregation covers the key owner's entire account usage, not just calls made with that key.

Usage summary#

GET/v1/usage/summary

Returns the last-24h totals (calls_24h · cost_24h_krw), the 7-day daily trend (cost_by_day), and the top-5 models over the last 30 days (cost_by_model) in one call.

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}
  ]
}

Request log#

GET/v1/usage/requests

Returns your individual call history, paginated. Each item includes token usage, cost_krw (the billed amount), BYOK flag and fee, latency, status code, and error message.

Parameter	Type	Required	Description
period	string	Optional	`1d` \| `7d` \| `30d` \| `90d`. Omit for all time.
model	string	Optional	Filter by an exact model ID.
outcome	string	Optional	`success` \| `error`. Filter by outcome.
page	integer	Optional	≥ 1. Default 1.
size	integer	Optional	1 to 100. Default 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
}

Intent distribution#

GET/v1/usage/classifications

Returns the distribution of request intents classified by Smart Mode. It aggregates counts only — no prompt text is stored or exposed. Categories are vision, code, translation, creative, reasoning, and general.

Parameter	Type	Required	Description
period	string	Optional	`1d` \| `7d` \| `30d` \| `90d`. Omit for all time.

200 OK

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

items may be empty until Smart Mode data accrues.

Activity log#

GET/v1/usage/audit-log

Returns your recent security and activity events (API key created, management key created, etc.). Each event includes event_type, severity, resource_type, and detail.

Parameter	Type	Required	Description
limit	integer	Optional	Number of events to return. Default 50, max 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"
    }
  ]
}