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.

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 $PLEUM_API_KEY). Keys without the scope get a 403. A key with only usage:read is 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.
api_key_id	uuid	Optional	Filter by API key ID.
model	string	Optional	Filter by an exact model ID.
provider	string	Optional	Filter by provider ID.
outcome	string	Optional	`success` \| `error`. Filter by outcome.
is_byok	boolean	Optional	true keeps only BYOK calls; false keeps only non-BYOK calls.

request

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

200 OK

{
  "group_by": "model",
  "days": 30,
  "items": [
    {
      "key": "gpt-5.5",
      "cost_krw": 48200.4,
      "input_tokens": 8120000,
      "output_tokens": 912000,
      "calls": 1420
    },
    {
      "key": "claude-sonnet-4-6",
      "cost_krw": 31900.7,
      "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 total for the requested days window (cost_period_krw), the daily trend (cost_by_day) and the top-5 models (cost_by_model) in one call.

Parameter	Type	Required	Description
days	integer	Optional	Aggregation window in days. 1 to 365, default 30.
from_ts	string	Optional	Start of a custom range (ISO 8601). Send it together with `to_ts`; it is used instead of `days`. The range is at most 92 days.
to_ts	string	Optional	End of a custom range (ISO 8601). Send it together with `from_ts`.
api_key_id	uuid	Optional	Filter by API key ID.
model	string	Optional	Filter by an exact model ID.
provider	string	Optional	Filter by provider ID.
outcome	string	Optional	`success` \| `error`. Filter by outcome.
is_byok	boolean	Optional	true keeps only BYOK calls; false keeps only non-BYOK calls.

200 OK

{
  "days": 30,
  "calls_24h": 142,
  "cost_24h_krw": 3870.3,
  "cost_period_krw": 80101.1,
  "cost_by_day": [
    {"date": "2026-06-26", "cost_krw": 1200.5, "calls": 40}
  ],
  "cost_by_model": [
    {"model": "gpt-5.5", "cost_krw": 2600.2, "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 category. The category is in error_category (error_message carries the same value) as a fixed string such as rate_limited or invalid_request, and is null for successful calls.

Parameter	Type	Required	Description
period	string	Optional	`1d` \| `7d` \| `30d` \| `90d` \| `365d`. If omitted, the last 30 days.
from_ts	string	Optional	Start of a custom range (ISO 8601). Send it together with `to_ts`; it is used instead of `days`. The range is at most 92 days.
to_ts	string	Optional	End of a custom range (ISO 8601). Send it together with `from_ts`.
api_key_id	uuid	Optional	Filter by API key ID.
model	string	Optional	Filter by an exact model ID.
provider	string	Optional	Filter by provider ID.
outcome	string	Optional	`success` \| `error`. Filter by outcome.
is_byok	boolean	Optional	true keeps only BYOK calls; false keeps only non-BYOK calls.
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-5.5",
      "provider": "openai",
      "input_tokens": 1240,
      "output_tokens": 312,
      "total_tokens": 1552,
      "cache_read_tokens": 1024,
      "cost_krw": 58.4,
      "is_byok": false,
      "byok_fee_krw": 0,
      "latency_ms": 1841,
      "ttft_ms": 412,
      "status_code": 200,
      "error_message": null,
      "error_category": 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 Auto. It aggregates counts only. Categories are vision, agent, code_debug, code, math, translation, creative, reasoning, and general.

Parameter	Type	Required	Description
period	string	Optional	`1d` \| `7d` \| `30d` \| `90d` \| `365d`. 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 Auto requests have been recorded.

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. detail is an object with event-specific information, or null.

Parameter	Type	Required	Description
limit	integer	Optional	Number of events to return. Default 50, max 200.
period	string	Optional	`7d` \| `30d` \| `90d`. Default `30d`.
severity	string	Optional	`info` \| `warning` \| `critical`. Filter by severity.
event_type	string	Optional	Filter by an exact event type.

200 OK

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