Usage
Query usage records
Query your workspace's metered usage volume, in characters, tokens, and seconds, grouped into UTC time buckets.
/usage/v1/recordsThis API is Experimental and may change. In rare cases, historical numbers may be adjusted.
Usage data measures characters, tokens, and audio seconds, not invoiced amounts. It is grouped into whole UTC buckets: days by default, or hours for ranges up to 30 days.
Data is complete up to readTime, roughly one hour behind real time. Fetch recent windows again before treating them as final. History covers the last 30 days. The API returns int64 metric values 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_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: Not available yet.
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. Not available yet — servers reject it with FAILED_PRECONDITION.
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". 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.