Usage
Query usage records
Returns metered usage volume (characters, tokens, seconds) for the workspace that owns the API key, aggregated into UTC time buckets. Volume only — not invoiced amounts. Data is complete up to readTime (roughly one hour behind real time); re-fetch recent windows rather than treating them as final. History depth: the last 30 days. int64 values are returned as JSON strings.
/usage/v1/recordsThis is an Experimental release: the API is subject to change, and historical numbers may be adjusted in rare cases.
Usage data is aggregated into whole UTC buckets (days by default, hours for ranges up to 30 days) and reflects metered volume — characters, tokens and audio seconds — not invoiced amounts. Data is complete up to readTime, roughly one hour behind real time: re-fetch recent windows rather than treating them as final. History is available for the last 30 days. int64 metric values are returned as JSON strings.
Authorizationstringrequired
Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY.
startTimestringrequired
Range start, inclusive.
endTimestringrequired
Range end, exclusive.
granularityenum<string>default: "GRANULARITY_DAY"
Bucket size; defaults to GRANULARITY_DAY.
GRANULARITY_UNSPECIFIED: Unspecified; treated asGRANULARITY_DAY.GRANULARITY_HOUR: Calendar hour in UTC. Supported for ranges up to 30 days; longer ranges
are rejected with INVALID_ARGUMENT.
GRANULARITY_DAY: Default. Calendar day in UTC.GRANULARITY_MONTH: Reserved; not offered in v1.
Available options:GRANULARITY_UNSPECIFIEDGRANULARITY_HOURGRANULARITY_DAYGRANULARITY_MONTH
timeZonestring
IANA time zone for bucket boundaries. Not supported in v1 — buckets are always computed in UTC. Clients must leave this unset; servers reject non-empty values with INVALID_ARGUMENT.
groupByenum<string>[]
Dimensions to group by. Omitted: one row per time bucket, all models summed. USAGE_DIMENSION_API_KEY is filter-only in v1 — servers reject it here with INVALID_ARGUMENT.
USAGE_DIMENSION_UNSPECIFIED: Unspecified; invalid as agroup_byvalue.USAGE_DIMENSION_SERVICE: tts | llm | stt | ...USAGE_DIMENSION_MODEL: e.g. tts-2.0. The v1 main path.USAGE_DIMENSION_SERVICE_PROVIDER: Upstream inference provider.USAGE_DIMENSION_API_KEY: Filter only in v1;group_bysupport later.
servicesstring[]
Service filter (e.g. "tts"). Open strings; repeated values mean IN semantics — same for the other dimension filters below.
modelsstring[]
Model filter (e.g. "tts-2.0").
serviceProvidersstring[]
Service-provider filter.
apiKeyIdsstring[]
Same-workspace API-key filter. Rejected when the backing store cannot apply it faithfully (never silently ignored).
metricsstring[]
Metric selection (e.g. "characters", "input_tokens"). Empty means all consumption metrics for the requested services; never plan fees.
pageSizeinteger
Maximum records per page; values above the server maximum are coerced.
pageTokenstring
Opaque cursor from a previous response.
usageRecordsobject[]
Usage rows for the requested range: one per time bucket × dimension group.
Show child attributes
startTimestring
Bucket start, inclusive.
endTimestring
Bucket end, exclusive.
groupobject
Dimension key -> value for this row; present keys mirror the requested group_by set. Keys are stable lower_snake_case names matching UsageDimension: "service", "model", "service_provider" (later "api_key_id"). Example: "model": "tts-2.0".
metricsobject
Metric name -> value. Adding a metric is one more entry (additive).
nextPageTokenstring
Empty when there are no further pages.
totalSizeinteger
Omitted by default (expensive to compute per page); explicit presence so clients can tell "absent" from a real 0.
readTimestring
Freshness watermark: the returned data is complete up to this time. Usage is not a live counter; clients should re-fetch recent windows rather than assume immutability.