Hanzo
OpenapiLink

Reports usage samples from the device collector.

Reports usage samples from the device collector.

POST /v1/link/usage

Addresshttps://api.hanzo.ai/v1/link/usage
MethodPOST
Operationpost_link_usage
AuthAuthorization: Bearer $HANZO_API_KEY

Reports usage samples from the device collector.

It ingests a batch of usage samples and answers with how many were accepted, whether history was durably stored, and the links they refreshed. A report also REFRESHES one link per distinct (machine, provider, account) it names, so a running collector keeps the accounts overview current without a separate registration call.

A caller can only ever report for THEMSELVES: org and subject come from the validated bearer, never from the body, so no sample can be attributed to another user or tenant. History is FAIL-SOFT and stored says which happened — a warehouse outage still accepts the report and refreshes the links rather than failing the device, and answers 202 either way. Send either one sample inline or up to 256 in samples; an empty batch or an over-long one is 400, as is a provider, window class or kind outside the closed vocabulary — an unrecognized window is refused rather than rewritten, because a silently reclassified sample would fill a dashboard with a class nobody reported.

Request

43 fields, body application/json (required).

FieldInTypeRequiredDescription
accountbodystring
cachedInputTokensbodyinteger
confidencebodystring
costCentsbodyinteger
costLimitCentsbodyinteger
currencybodystring
inputTokensbodyinteger
kindbodystring
lanebodystring
machinebodystring
outputTokensbodyinteger
planbodystring
providerbodystring
requestsbodyinteger
resetsAtbodystring
samplesbodyreadingReq[]Samples is the batch form, up to 256 samples; leave it empty to send one sample inline on the same fields.
samples[].accountbodystringAccount is the provider-side account the sample belongs to.
samples[].cachedInputTokensbodyintegerCachedInputTokens is the window's cached-prompt-token count.
samples[].confidencebodystringConfidence says how real the counters are, as the meter graded itself.
samples[].costCentsbodyintegerCostCents is the window's spend in cents, as the provider's meter states it.
samples[].costLimitCentsbodyintegerCostLimitCents is the window's spend cap in cents, when the meter knows one.
samples[].currencybodystringCurrency is the ISO currency the cost fields are stated in.
samples[].inputTokensbodyintegerInputTokens is the window's prompt-token count.
samples[].kindbodystringKind is subscription or apikey; anything else is refused.
samples[].lanebodystringLane names the meter's own lane label for this measurement.
samples[].machinebodystringMachine is the machine the collector observed the account on.
samples[].outputTokensbodyintegerOutputTokens is the window's completion-token count.
samples[].planbodystringPlan is the provider plan label the account is on.
samples[].providerbodystringProvider is the AI provider whose meter reported this sample.
samples[].requestsbodyintegerRequests is the window's request count.
samples[].resetsAtbodystringResetsAt is when the window resets, RFC 3339, bounded.
samples[].syntheticbodybooleanSynthetic marks a sample the collector derived rather than observed.
samples[].totalTokensbodyintegerTotalTokens is the window's total token count.
samples[].usedPctbodynumberUsedPct is how much of the window's allowance is consumed, clamped 0..100.
samples[].windowbodystringWindow is the window class, one of 6h, day, week, month; anything else is refused rather than silently reclassified.
samples[].windowMinutesbodyintegerWindowMinutes is the window's length as the meter reported it.
samples[].windowStartbodystringWindowStart is when the measured window opened, RFC 3339, bounded to a sane interval around now.
syntheticbodyboolean
totalTokensbodyinteger
usedPctbodynumber
windowbodystring
windowMinutesbodyinteger
windowStartbodystring

Response

StatusBodyMeaning
202ingestRespaccepted

202 body — 18 fields.

FieldInTypeAlwaysDescription
acceptedbodyintegerAccepted is how many samples this report landed.
linksbodylinkView[]Links is the link row each distinct (machine, provider, account) in the batch refreshed.
links[].accountbodystringAccount is the provider-side account identifier, when the collector knows it.
links[].billingbodystringBilling is how this account's inference bills — plan (the user's own subscription, metered here for visibility only) or commerce (the gateway path).
links[].createdAtbodystringCreatedAt is when the link was first registered, RFC 3339 UTC.
links[].hostbodystringHost is the machine's human hostname label, from its most recent report.
links[].idbodystringID is the link's opaque handle ("link_" + 32 hex chars).
links[].kindbodystringKind is how the account authenticates: subscription or apikey.
links[].lastSeenbodystringLastSeen is when the account last reported, RFC 3339 UTC.
links[].machinebodystringMachine is the stable machine identifier the collector reports.
links[].osbodystringOS is the machine's operating system label.
links[].planbodystringPlan is the provider plan label (e.g.
links[].providerbodystringProvider is the AI provider this account belongs to (claude, openai, hanzo…).
links[].statusbodystringStatus is linked or revoked.
links[].updatedAtbodystringUpdatedAt is when the link was last refreshed, RFC 3339 UTC.
links[].usagebodyanyUsage is the last good usage snapshot, clamped and re-serialized to known fields at ingest.
links[].userbodystringUser is the owning subject — the validated caller who registered the link.
storedbodybooleanStored reports whether history was durably written; false means the warehouse was unavailable and only the link rows were refreshed.

Failure carries the platform error shape — see Errors.

Examples

hanzo links usage create

Link API · All Hanzo APIs · Interactive reference

How is this guide?

On this page