Get customer usage

Call getCustomerUsage() to read usage and rate-limit information for the authenticated customer.


const usage = await client.getCustomerUsage()

Read usage allowances


const usage = await client.getCustomerUsage()
 
for (const limit of usage.usageLimits) {
  console.log({
    metric: limit.allowanceMetric,
    used: limit.rawAmount,
    allowance: limit.allowanceValue,
    remaining: limit.remaining,
    usedPercentage: limit.usedPercentage,
    scopeKind: limit.scopeKind,
    scopeValue: limit.scopeValue
  })
}

Each usage-limit item contains:

Field	Type	Description
`id`	`string`	The usage record ID.
`rawAmount`	`number`	The amount consumed in the current billing period.
`allowanceValue`	`number`	The configured allowance.
`allowanceMetric`	`string`	The unit being measured, such as requests, tokens, characters, file bytes, or audio duration.
`remaining`	`number`	The remaining allowance.
`usedPercentage`	`number`	The percentage of the allowance already consumed.
`scopeKind`	`string`	The method used to match requests to the rule.
`scopeValue`	`string`	The model identifier or pattern attached to the rule.

Read rate-limit rules

The same response contains the customer’s rate-limit rules:


for (const limit of usage.rateLimits) {
  console.log({
    allowance: limit.allowanceValue,
    metric: limit.allowanceMetric,
    frequency: limit.rateLimitFrequency,
    scopeKind: limit.scopeKind,
    scopeValue: limit.scopeValue
  })
}

A rate-limit entry describes the configured rule. It does not include the amount consumed within the active rate-limit window.

Get the aggregate percentage

Use getCustomerUsagePercentage() when the interface needs one percentage:


const { percentage } = await client.getCustomerUsagePercentage()
 
renderUsageBar(percentage)

The response is:


type CustomerUsagePercentage = {
  percentage: number
}

Use getCustomerUsage() for a detailed account or billing screen. Use getCustomerUsagePercentage() for a compact progress indicator.