Skip to content

Prudai Developer API: usage

Your organisation’s usage per period.

Base URL https://api.prudai.com/v1. Logging in is in Login, scopes in Scopes and permissions, errors in Errors. Overview.

MethodPathWhat it doesState
GET/v1/usageAggregated usageIn production

Aggregated usage

GET /v1/usage

Usage of all keys of your organisation in the same environment as the calling key (live keys see live usage, test keys see test usage), aggregated per UTC day, key, model and/or operation. Contains metadata only, never content. Credit amounts are null until credit accounting is enabled; free operations then cost 0. Source grouping and filtering are reserved and return 422 unsupported_parameter until source metadata is recorded. Personal credentials require an Owner or Admin role.

  • State: in production.
  • Scope: account:usage:read
  • Approval: none, no extra step.

Parameters

  • start_date query · string (date) required
    First UTC day (inclusive).
  • end_date query · string (date)
    Last UTC day (inclusive). Defaults to today. The range is at most 366 days.
  • group_by query · array<string>
    Dimensions to group by, comma-separated. Default day. The reserved source dimension returns 422 unsupported_parameter. One of: day, key, model, operation, source
  • key_id query · string
    Only usage of this key. Public id of an API key (not the secret). pattern ^key_[A-Za-z0-9]{20}$
  • model query · string
    Only usage of this model (product or product/specialisation). A product, optionally followed by / and a specialisation slug (e.g. leo/arbeidsrecht). max length 80 · pattern ^(leo|leo-fiscaal|zia|vera|bever|maia)(/[a-z0-9]+(-[a-z0-9]+)*)?$
  • operation query · string
    Only usage of this operation. The metered manifest operation identifier. Legacy dotted operation names are accepted as filters. pattern ^[A-Za-z][A-Za-z0-9_.-]{0,99}$
  • source_id query · string
    Reserved source filter. Currently returns 422 unsupported_parameter. Public source id from the Prudai source catalogue. max length 80 · pattern ^[a-z0-9]+(-[a-z0-9]+)*$

Responses

StatusMeaning
200The usage report.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution).
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
429Rate limit, concurrency limit, Ultra daily quota or fair-use limit of the free sources operations exceeded.
500Unexpected error on Prudai’s side. Not charged, except work that completed before the failure (reported in details.charged_credits).

Fields in data (200)

  • object string
    usage.report
  • start_date string (date)
  • end_date string (date)
  • group_by array<string>
    One of: day, key, model, operation, source
  • data array<UsageBucket>
  • data[].date string (date)
    Set when grouped by day. may be null
  • data[].key_id string
    Set when grouped by key. may be null
  • data[].key_name string
    may be null
  • data[].model string
    Set when grouped by model (null for operations without a model, such as search). may be null
  • data[].operation string
    Set when grouped by operation. may be null
  • data[].source_id string
    Set when grouped by source. may be null
  • data[].requests integer
    min 0
  • data[].failed_requests integer
    min 0
  • data[].input_tokens integer
    min 0
  • data[].cached_input_tokens integer
    min 0
  • data[].output_tokens integer
    min 0
  • data[].reasoning_tokens integer
    min 0
  • data[].priced_tool_calls integer
    min 0
  • data[].source_requests integer
    min 0
  • data[].credits number
    Null while credit accounting is disabled or the metered amount is unavailable. may be null
  • totals UsageCounters
  • totals.requests integer
    min 0
  • totals.failed_requests integer
    Requests that ended in an error (not charged unless partial work was charged). min 0
  • totals.input_tokens integer
    min 0
  • totals.cached_input_tokens integer
    min 0
  • totals.output_tokens integer
    min 0
  • totals.reasoning_tokens integer
    min 0
  • totals.priced_tool_calls integer
    min 0
  • totals.source_requests integer
    /sources/* and /citations/verify requests (free at launch, counted here). min 0
  • totals.credits number
    Null while credit accounting is disabled or the metered amount is unavailable. may be null
curl
curl -s "https://api.prudai.com/v1/usage?start_date=%3Cstart_date%3E" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo usage
Response 200
{
"object": "usage.report",
"start_date": "2026-11-05",
"end_date": "2026-11-05",
"group_by": [
"day"
],
"data": [
{
"date": "2026-11-05",
"key_id": "string",
"key_name": "string",
"model": "leo",
"operation": "listModels",
"source_id": "string",
"requests": 1,
"failed_requests": 1,
"input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1,
"reasoning_tokens": 1,
"priced_tool_calls": 1,
"source_requests": 1,
"credits": 1
}
],
"totals": {
"requests": 1,
"failed_requests": 1,
"input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1,
"reasoning_tokens": 1,
"priced_tool_calls": 1,
"source_requests": 1,
"credits": 1
}
}