Usage

Get Token Usage By Dimension

$client->beta->organization->analytics->usage->list(\Datetime startingAt, ?list<string> actorIDs, ?list<AnalyticsActorType> actorTypes, ?list<string> agentIDs, ?list<string> apiKeyIDs, ?list<AnalyticsClaudeTagCategory> claudeTagCategories, ?list<string> claudeTagUserIDs, ?list<AnalyticsContextWindow> contextWindows, ?list<string> deploymentIDs, ?\Datetime endingAt, ?list<string> environmentIDs, ?bool excludeDeletedUsers, ?list<BetaAnalyticsUsageGroupBy> groupBy, ?list<AnalyticsInferenceGeoFilter> inferenceGeos, ?int limit, ?list<string> models, ?AnalyticsUsageCostSortOrder order, ?BetaAnalyticsUsageOrderBy orderBy, ?string page, ?list<AnalyticsUsageCostProductFilter> products, ?list<string> rbacGroupIDs, ?list<AnalyticsServiceTier> serviceTiers, ?list<string> sessionIDs, ?list<string> slackChannelIDs, ?list<AnalyticsSpeed> speeds, ?AnalyticsTimeBucketWidth timeBucketWidth, ?list<string> userProfileIDs, ?list<string> workspaceIDs, ?list<AnthropicBeta> betas): ReportPageCursor<BetaAnalyticsUsageItem>

GET/v1/organizations/analytics/usage

Requires anthropic-beta: analytics-usage-cost-2026-08-24. How to send beta headers

Get token usage across a date range, broken out by dimension.

Models

class BetaAnalyticsUsageGroup { $actor; $actorType; $agentID; /* 16 more */ }

enum BetaAnalyticsUsageGroupBy

One of the following:

"actor"

"actor_type"

"agent_id"

"api_key_id"

"claude_tag_category"

"claude_tag_user_id"

"context_window"

"deployment_id"

"environment_id"

"inference_geo"

"model"

"product"

"rbac_group_id"

"service_tier"

"session_id"

"slack_channel_id"

"speed"

"user_profile_id"

"workspace_id"

class BetaAnalyticsUsageItem { $endingAt; $group; $startingAt; $usage; }

\Datetime endingAt

End of the period this row covers (exclusive), as an RFC 3339 UTC timestamp: the end of the row's time bucket when a time-bucket width is set; otherwise the requested ending_at (or, when omitted, the earlier of now and starting_at plus 31 days) rounded down to the hour, because without a time bucket the report covers whole hours.

BetaAnalyticsUsageGroup group

The dimension values this row's usage is broken out by.

\Datetime startingAt

Start of the period this row covers (inclusive), as an RFC 3339 UTC timestamp: the start of the row's time bucket when a time-bucket width is set, otherwise the requested starting_at rounded down to the hour.

BetaAnalyticsUsageMetrics usage

Token usage for this row.

class BetaAnalyticsUsageMetrics { $cacheCreation; $cacheReadInputTokens; $outputTokens; /* 4 more */ }

BetaCacheCreation cacheCreation

The number of input tokens for cache creation.

int cacheReadInputTokens

The number of input tokens read from the cache.

int outputTokens

The number of output tokens generated.

?int requests

Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with product: null).

AnalyticsServerToolUse serverToolUse

Server-side tool usage metrics.

int totalTokens

Total token count across all token types. This is the value the default order_by (total_tokens) sorts on.

int uncachedInputTokens

The number of uncached input tokens processed.

enum BetaAnalyticsUsageOrderBy

One of the following:

"output_tokens"

"requests"

"time"

"total_tokens"

"uncached_input_tokens"