Skip to navigation
Guides

Check usage

See what your workspace consumed, and what a run will cost before you start it.

Report your workspace’s usage over a rolling window (30d, 60d, or 90d). Needs the workspace:read scope.

from onepin import OnepinClient
client = OnepinClient()
summary = client.usage.usage_summary(range="30d").data
by_language = client.usage.usage_by_language(range="30d").data
activity = client.usage.usage_activity(range="30d").data

What the summary counts

The summary reports several different populations, and they are deliberately not addable to each other:

FieldCountsUnit
charactersCharacters processed across the workspacecharacters
audio.total_msDelivered audio length — the delivered take per generator on each line, retries excludedmilliseconds
corrected.totalWords respliced by the Pronunciation Correctorwords
linesScript lines generatedlines
runsRun counts by statusruns
creditsCredit consumption and quota for your billing periodcredits

Volume synthesized through a connected provider key is counted here like any other — characters and audio.total_ms include it — while it charges 0 credits. Usage and credits are two different questions, and BYOK is where they diverge most visibly.

corrected.total is in words, not characters — never add it to characters. And audio.total_ms is a narrower population than the per-workflow runs summary’s delivered_audio_ms, which counts completed runs only. The two are not expected to reconcile.

Estimate a run before you start it

onepin workflows preview-run <WORKFLOW_ID>
est = client.workflows.preview_run(workflow_id).data

Alongside min_credits / expected_credits / max_credits and can_run, the estimate now tells you whether the run will spill past your allowance:

FieldMeaning
will_incur_overageThe run is expected to go past your included credits
estimated_overage_centsWhat that spill is expected to cost, in cents
overage_rate_cents_per_creditThe rate it’s charged at; null when your plan has no overage rate

Credits, buckets, and overage

Credits come out of two buckets, and the distinction matters when you’re reading a balance from GET /api/v1/users/me/credits:

  • monthly_balance — the current paid cycle’s allowance. Replaced at each renewal, and 0 on Free.
  • free_balance — a one-time lifetime grant. Never expires, and spent last, after the monthly bucket.

balance is the sum of the two and is what gating decisions use (remaining is a display alias of it). overage_cents is what you’ve been billed past your allowance so far this cycle. credits_absorbed is the sub-credit remainder discounted by floor-rounding — Onepin’s rounding in your favour, not a charge.

Your plan’s own limits — including overage_rate_cents_per_credit, whether credits renew monthly or are one_time, and whether downloads are enabled — come from GET /api/v1/users/me/limits, or GET /api/v1/workspaces/{workspace_id}/plan for the workspace-scoped view (which resolves to the organization’s plan on an org workspace).

The overage, audio, and corrected-word fields are new. They are live on the API today; the Python SDK’s typed models pick them up in its next release, so read them off the response payload until then.