Claude Platform Docs

Get Cost By Dimension

$ ant beta:organization:analytics:cost list
GET/v1/organizations/analytics/cost
Requires anthropic-beta: analytics-usage-cost-2026-08-24. Learn how to send beta headers.

Get cost in USD across a date range, broken out by dimension.

Returns one row per combination of the requested group_by[] dimensions (and time bucket, when time_bucket_width is set) that has cost in the range, ranked by spend or ordered by time bucket; every combination is returned across pages. With no group_by[] and no time_bucket_width, a single row aggregates the whole range. Includes all cost, whether or not it is attributable to a seat user. Requires an API key with the read:analytics scope, or an Admin API key.

Parameters
--starting-at: string⁠Query parameter

Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.

formatdate-time
--actor-id: optional array of string⁠Query parameter

Filter to usage attributed to specific identities, by tagged ID: a user_..., svac_... (service account), or apikey_... ID. An apikey_ entry matches only usage attributed to the key itself, not usage on that key attributed to a user or service account (use api_key_ids[] for every request a key authenticated). Federated identities have no tagged ID; select them with actor_types[]. Use group_by[]=actor to break out per-identity values.

maxItems100
--actor-type: optional array of BetaAnalyticsActorType⁠Query parameter

Filter to usage attributed to specific kinds of identity. Use group_by[]=actor_type to break out per-kind values.

maxItems100
One of the following:
"api_actor"
"federated_actor"
"service_account_actor"
"user_actor"
--agent-id: optional array of string⁠Query parameter

Filter to usage incurred by sessions of specific Claude Managed Agents agents. Use group_by[]=agent_id to break out per-agent values. Claude Platform organizations only.

maxItems100
--api-key-id: optional array of string⁠Query parameter

Filter to usage authenticated by specific API keys, by tagged API key ID (apikey_...), whichever identity the usage is attributed to. Include an empty entry (api_key_ids[]=) to also match usage that no API key authenticated. Use group_by[]=api_key_id to break out per-key values; usage without a key has a null api_key_id. Claude Platform organizations only.

maxItems100
--claude-tag-category: optional array of BetaAnalyticsClaudeTagCategory⁠Query parameter

Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. Use group_by[]=claude_tag_category to break out per-category values.

maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
--claude-tag-user-id: optional array of string⁠Query parameter

Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example U0123ABCDEF), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use group_by[]=claude_tag_user_id to break out per-user values.

maxItems100
--context-window: optional array of BetaAnalyticsContextWindow⁠Query parameter

Filter to specific context-window pricing tiers. Use group_by[]=context_window to break out per-tier values.

maxItems100
One of the following:
"0-200k"
"200k-1M"
--deployment-id: optional array of string⁠Query parameter

Filter to usage incurred by Claude Managed Agents sessions that specific deployments started. Use group_by[]=deployment_id to break out per-deployment values. Claude Platform organizations only.

maxItems100
--ending-at: optional string⁠Query parameter

End of range, exclusive. Required when time_bucket_width is set. Without time_bucket_width, defaults to the earlier of now and starting_at + 31 days. The range may span at most 31 days.

formatdate-time
--environment-id: optional array of string⁠Query parameter

Filter to usage incurred by Claude Managed Agents sessions that ran in specific environments. Use group_by[]=environment_id to break out per-environment values. Claude Platform organizations only.

maxItems100
--exclude-deleted-users: optional boolean⁠Query parameter

If true, omit rows whose actor is a user_actor with deleted: true. Requires group_by[]=actor. Rows for other actor types, and rows whose actor is null, are always kept. A page may contain fewer than limit rows; use has_more and next_page to paginate as usual.

--group-by: optional array of BetaAnalyticsCostGroupBy⁠Query parameter

Dimensions to break cost out by (at most 5, not counting cost_type and token_type): one row per combination of their values with cost in the range (and per time bucket, when time_bucket_width is set), every combination returned across pages rather than a capped top set. cost_type and token_type do not count toward limit: cost_type returns one row per cost component (tokens, web search, code execution, and session_usage, Claude Managed Agents session time); token_type returns one row per token type, each with cost_type: "tokens"; combining both returns the per-token-type rows plus the web-search, code-execution and session-usage rows. When omitted, a single row aggregates the whole range.

maxItems100
One of the following:
"actor"
"actor_type"
"agent_id"
"api_key_id"
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"cost_type"
"deployment_id"
"environment_id"
"inference_geo"
"model"
"organization_id"
"product"
"rbac_group_id"
"service_tier"
"session_id"
"slack_channel_id"
"speed"
"token_type"
"user_profile_id"
"workspace_id"
--inference-geo: optional array of BetaAnalyticsInferenceGeoFilter⁠Query parameter

Filter to specific inference regions. not_available matches rows where the region is unset. Use group_by[]=inference_geo to break out per-region values.

maxItems100
One of the following:
"global"
"not_available"
"us"
--limit: optional number⁠Query parameter

Number of rows per page (1-1000, default 20). cost_type/token_type fan-out rows (cost endpoint only) do not count toward this limit, so data can exceed it.

minimum1
maximum1000
--model: optional array of string⁠Query parameter

Models to include. Defaults to all models. Use group_by[]=model to break out per-model values.

maxItems100
--order: optional BetaAnalyticsUsageCostSortOrder⁠Query parameter

Sort direction of the order_by metric, or of the time buckets when order_by is time and time_bucket_width is set. Defaults to desc.

One of the following:
"asc"
"desc"
--order-by: optional BetaAnalyticsCostOrderBy⁠Query parameter

Row order. A metric ranks rows by that metric in the order direction. time orders rows by time bucket in the order direction (newest first by default) and, within a bucket, by amount, highest first. time takes effect only with time_bucket_width; without it, time is the same as amount. Defaults to amount.

One of the following:
"amount"
"list_amount"
"time"
--organization-id: optional array of string⁠Query parameter

Filter a parent organization's report to specific child organizations, by organization UUID or org_ ID; an ID that is not one of its child organizations matches nothing. Requires an API key created at the parent organization level. Use group_by[]=organization_id to break out per-organization values.

maxItems100
--page: optional string⁠Query parameter

Opaque cursor from a previous response's next_page field.

--product: optional array of BetaAnalyticsUsageCostProductFilter⁠Query parameter

Product surfaces to include. Defaults to all products.

maxItems100
One of the following:
"chat"
"chat_cowork_unified"
"claude_code"
"claude_console"
"claude_design"
"claude_in_chrome"
"claude_tag"
"cowork"
"managed_agents_api"
"message_batches_api"
"messages_api"
"office_agent"
--rbac-group-id: optional array of string⁠Query parameter

Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (rbac_group_...) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.

maxItems100
--service-tier: optional array of BetaAnalyticsServiceTier⁠Query parameter

Filter to specific service tiers. Use group_by[]=service_tier to break out per-tier values. Claude Platform organizations only; matches nothing for a Claude Enterprise organization.

maxItems100
One of the following:
"batch"
"flex"
"flex_discount"
"priority"
"priority_on_demand"
"standard"
--session-id: optional array of string⁠Query parameter

Filter to usage incurred by specific Claude Managed Agents sessions, by tagged session ID (sesn_...). Use group_by[]=session_id to break out per-session values. Claude Platform organizations only.

maxItems100
--slack-channel-id: optional array of string⁠Query parameter

Filter to usage originating from specific Slack channels. Use group_by[]=slack_channel_id to break out per-channel values.

maxItems100
--speed: optional array of BetaAnalyticsSpeed⁠Query parameter

Filter to fast or standard inference mode. Use group_by[]=speed to break out per-mode values.

maxItems100
One of the following:
"fast"
"standard"
--time-bucket-width: optional BetaAnalyticsTimeBucketWidth⁠Query parameter

Time-bucket granularity. When set, rows are returned per time bucket (one per bucket and dimension combination with usage) and each row's starting_at and ending_at are that bucket's bounds; the time bucket counts toward limit. ending_at is required when time_bucket_width is set, and with time_bucket_width="1m" the range may span at most 24 hours. When omitted, each row aggregates the requested range with starting_at and ending_at each rounded down to the hour.

One of the following:
"1d"
"1h"
"1m"
--user-profile-id: optional array of string⁠Query parameter

Filter to usage attributed to specific user profiles, by tagged user profile ID (uprof_...). Use group_by[]=user_profile_id to break out per-profile values. Claude Platform organizations only.

maxItems100
--workspace-id: optional array of string⁠Query parameter

Filter to usage in specific workspaces, by tagged workspace ID (wrkspc_...). Use group_by[]=workspace_id to break out per-workspace values. Claude Platform organizations only; matches nothing for a Claude Enterprise organization.

maxItems100
--beta: optional array of AnthropicBeta⁠Header parameter

This endpoint is in beta: requests must send analytics-usage-cost-2026-08-24 in this header.

One of the following:
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"output-128k-2025-02-19"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"ce-plugins-2026-09-01"
"spend-limit-reads-2026-09-26"
"telemetry-destinations-2026-08-11"
"webhooks-2026-10-07"
"admin-user-sign-out-2026-10-08"
"message-threads-2026-08-12"
"analytics-usage-cost-2026-08-24"
"experimental-claude-tag-2026-10-21"
"user-profiles-billing-2026-10-01"
"message-batches-2024-09-24"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"prompt-caching-2024-07-31"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"pdfs-2024-09-25"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"token-counting-2024-11-01"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"token-efficient-tools-2025-02-19"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"files-api-2025-04-14"⁠Deprecated
Sending this value selects the beta response shapes. Removing it moves you to the current shapes, so follow the migration steps: https://platform.claude.com/docs/en/build-with-claude/files#migrate-from-files-api-2025-04-14
"extended-cache-ttl-2025-04-11"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"skills-2025-10-02"⁠Deprecated
Sending this value selects the beta response shapes. Removing it moves you to the current shapes, so follow the migration steps: https://platform.claude.com/docs/en/build-with-claude/skills-guide#migrate-from-skills-2025-10-02
"cache-diagnosis-2026-04-07"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"ce-user-management-2026-07-13"⁠Deprecated
This value is no longer needed. Remove it from your requests.
Returns
BetaAnalyticsFlatCostResponse: object{ data, data_refreshed_at, has_more, next_page }
data: array of BetaAnalyticsCostItem { cost, ending_at, group, starting_at }

Rows for this page, in the order set by order_by and order: one per combination of the group_by[] dimensions (and per time bucket, when time_bucket_width is set) with usage or cost in the range, or a single row when neither is set. Rows split out by cost_type or token_type (cost endpoint only) stay adjacent and are ranked as one unit.

cost: object{ amount, currency, list_amount, requests }

Cost for this row.

amount: string

Amount (post-discount, pre-credit) in fractional cents (minor units).

currency: string

Currency code for the cost amount. Currently always "USD".

list_amount: string

List-price amount (pre-discount) in fractional cents.

requests: number

Number of API requests in this row's scope. Null when group_by includes cost_type or token_type (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with product: null).

ending_at: string

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.

formatdate-time
group: object{ actor, actor_type, agent_id, 19 more }

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

starting_at: string

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.

formatdate-time
data_refreshed_at: string

RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case data is empty. Data beyond this watermark is incomplete; for stable results, set ending_at to this value or earlier. Data is typically refreshed every 4 hours. Values can be revised as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month the usage falls in; for example, values for October 1 can change until about November 7.

formatdate-time
has_more: boolean

Whether another page is available. When true, pass next_page as the page parameter to fetch it.

next_page: string

Opaque cursor for the next page, or null when has_more is false. Pass it as the page parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page.

Get Cost By Dimension
ant beta:organization:analytics:cost list \
  --starting-at ''\''2026-09-01T00:00:00Z'\'''
Returns Examples
Response 200
{
  "data": [
    {
      "cost": {
        "amount": "41280.000000",
        "currency": "USD",
        "list_amount": "51600.000000",
        "requests": 128
      },
      "ending_at": "2026-10-01T00:00:00Z",
      "group": {
        "actor": {
          "deleted": false,
          "email_address": "user@emaildomain.com",
          "name": "Jane Doe",
          "type": "user_actor",
          "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu"
        },
        "actor_type": "user_actor",
        "agent_id": "agent_01VHd3EAGJ6PLkP9LM7DDu3f",
        "api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
        "claude_tag_category": "dm",
        "claude_tag_user_id": "U0123ABCDEF",
        "context_window": "0-200k",
        "cost_type": "tokens",
        "deployment_id": "depl_01JFC6ihzZHtAuyHsaENdJhY",
        "environment_id": "env_017oTjuGedHtjhJauVC5xGJD",
        "inference_geo": "global",
        "model": "claude-opus-5-5",
        "organization_id": "12345678-1234-5678-1234-567812345678",
        "product": "chat",
        "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
        "service_tier": "standard",
        "session_id": "sesn_0187kPDyNCwibNNvfaPEApCJ",
        "slack_channel_id": "C0123ABCDEF",
        "speed": "fast",
        "token_type": "cache_creation.ephemeral_1h_input_tokens",
        "user_profile_id": "uprof_01M33NeYUQK2WV9PpYcsPHLi",
        "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
      },
      "starting_at": "2026-09-01T00:00:00Z"
    }
  ],
  "data_refreshed_at": "2026-10-01T04:02:11Z",
  "has_more": true,
  "next_page": "next_page"
}