usage_reports

Creates, updates, deletes, gets or lists a usage_reports resource.

Overview

Name	usage_reports
Type	Resource
Id	anthropic_admin.usage.usage_reports

Fields

The following fields are returned by SELECT queries:

list

Name	Datatype	Description
ending_at	string	End of the time bucket (exclusive) in RFC 3339 format.
▶results	array	List of usage items for this time bucket; multiple items when one or more `group_by[]` parameters are specified. Each item carries uncached_input_tokens, cache_creation, cache_read_input_tokens, output_tokens, server_tool_use, and the grouping dimensions (account_id, api_key_id, workspace_id, model, service_tier, service_account_id, context_window, inference_geo) which are null unless grouped by.
starting_at	string	Start of the time bucket (inclusive) in RFC 3339 format.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	starting_at	ending_at, bucket_width, group_by[], account_ids[], api_key_ids[], workspace_ids[], models[], service_tiers[], service_account_ids[], context_window[], inference_geos[], speeds[]	Get a Messages API usage report bucketed by time, optionally grouped and filtered. Each row is a time bucket carrying a results array with one item per group combination.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
starting_at	string	Time buckets that start on or after this RFC 3339 timestamp will be returned. Snapped to the start of the minute/hour/day in UTC.
account_ids[]	array	Restrict usage returned to the specified user account ID(s).
api_key_ids[]	array	Restrict usage returned to the specified API key ID(s).
bucket_width	string	Time granularity of the response data.
context_window[]	array	Restrict usage returned to the specified context window(s) - 0-200k or 200k-1M.
ending_at	string	Time buckets that end before this RFC 3339 timestamp will be returned.
group_by[]	array	Group by any subset of account_id, api_key_id, context_window, inference_geo, model, service_account_id, service_tier, speed, workspace_id. Grouping by speed requires the fast-mode-2026-02-01 beta header.
inference_geos[]	array	Restrict usage returned to the specified inference geo(s) - global, us, or not_available.
models[]	array	Restrict usage returned to the specified model(s).
service_account_ids[]	array	Restrict usage returned to the specified service account ID(s).
service_tiers[]	array	Restrict usage returned to the specified service tier(s) - batch, flex, flex_discount, priority, priority_on_demand, standard.
speeds[]	array	Restrict usage returned to the specified speed(s), fast or standard (Claude Code research preview). Requires the fast-mode-2026-02-01 beta header.
workspace_ids[]	array	Restrict usage returned to the specified workspace ID(s).

SELECT examples

list

Get a Messages API usage report bucketed by time, optionally grouped and filtered. Each row is a time bucket carrying a results array with one item per group combination.

SELECT
ending_at,
results,
starting_at
FROM anthropic_admin.usage.usage_reports
WHERE starting_at = '{{ starting_at }}' -- required
AND ending_at = '{{ ending_at }}'
AND bucket_width = '{{ bucket_width }}'
AND "group_by[]" = '{{ group_by[] }}'
AND "account_ids[]" = '{{ account_ids[] }}'
AND "api_key_ids[]" = '{{ api_key_ids[] }}'
AND "workspace_ids[]" = '{{ workspace_ids[] }}'
AND "models[]" = '{{ models[] }}'
AND "service_tiers[]" = '{{ service_tiers[] }}'
AND "service_account_ids[]" = '{{ service_account_ids[] }}'
AND "context_window[]" = '{{ context_window[] }}'
AND "inference_geos[]" = '{{ inference_geos[] }}'
AND "speeds[]" = '{{ speeds[] }}'
;