Claude Platform Docs

차원별 비용 조회

$client->beta->organization->analytics->cost->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<BetaAnalyticsCostGroupBy> groupBy, ?list<AnalyticsInferenceGeoFilter> inferenceGeos, ?int limit, ?list<string> models, ?AnalyticsUsageCostSortOrder order, ?BetaAnalyticsCostOrderBy 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<BetaAnalyticsCostItem>
GET/v1/organizations/analytics/cost
Requires anthropic-beta: analytics-usage-cost-2026-08-24. How to send beta headers

날짜 범위에 걸친 USD 비용을 차원별로 나누어 조회합니다.

범위 내에 비용이 있는 요청된 group_by[] 차원(및 time_bucket_width가 설정된 경우 시간 버킷)의 조합당 하나의 행을 반환하며, 지출액에 따라 순위가 매겨지거나 시간 버킷 순으로 정렬됩니다. 모든 조합은 여러 페이지에 걸쳐 반환됩니다. group_by[]와 time_bucket_width가 모두 없으면 단일 행이 전체 범위를 집계합니다. 시트 사용자에게 귀속되는지 여부와 관계없이 모든 비용이 포함됩니다. read:analytics 범위가 있는 API 키 또는 Admin API 키가 필요합니다.

Parameters
startingAt: \Datetime⁠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.

actorIDs?: optional list<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.

actorTypes?: optional list<AnalyticsActorType>⁠Query parameter

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

agentIDs?: optional list<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 Developer Platform organizations only.

apiKeyIDs?: optional list<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 Developer Platform organizations only.

claudeTagCategories?: optional list<AnalyticsClaudeTagCategory>⁠Query parameter

Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. dm usage is reported under the user's product rather than claude_tag, so combining this filter with products[]=claude_tag excludes it. Use group_by[]=claude_tag_category to break out per-category values.

claudeTagUserIDs?: optional list<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.

contextWindows?: optional list<AnalyticsContextWindow>⁠Query parameter

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

deploymentIDs?: optional list<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 Developer Platform organizations only.

endingAt?: optional \Datetime⁠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.

environmentIDs?: optional list<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 Developer Platform organizations only.

excludeDeletedUsers?: optional bool⁠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.

defaultfalse
groupBy?: optional list<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.

inferenceGeos?: optional list<AnalyticsInferenceGeoFilter>⁠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.

limit?: optional int⁠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.

default20
models?: optional list<string>⁠Query parameter

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

order?: optional AnalyticsUsageCostSortOrder⁠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.

orderBy?: 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.

page?: optional string⁠Query parameter

Opaque cursor from a previous response's next_page field.

products?: optional list<AnalyticsUsageCostProductFilter>⁠Query parameter

Product surfaces to include. Defaults to all products.

rbacGroupIDs?: optional list<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.

serviceTiers?: optional list<AnalyticsServiceTier>⁠Query parameter

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

sessionIDs?: optional list<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 Developer Platform organizations only.

slackChannelIDs?: optional list<string>⁠Query parameter

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

speeds?: optional list<AnalyticsSpeed>⁠Query parameter

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

timeBucketWidth?: optional AnalyticsTimeBucketWidth⁠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.

userProfileIDs?: optional list<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 Developer Platform organizations only.

workspaceIDs?: optional list<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 Developer Platform organizations only; matches nothing for a Claude Enterprise organization.

betas?: optional list<AnthropicBeta>⁠Header parameter

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

Returns
class BetaAnalyticsCostItem { $cost; $endingAt; $group; $startingAt; }
BetaAnalyticsCostMetrics cost

Cost for this row.

\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.

BetaAnalyticsCostGroup group

The dimension values this row's cost 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.

차원별 비용 조회
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Anthropic\Client;
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Organization\Analytics\AnalyticsActorType;
use Anthropic\Beta\Organization\Analytics\AnalyticsClaudeTagCategory;
use Anthropic\Beta\Organization\Analytics\AnalyticsContextWindow;
use Anthropic\Beta\Organization\Analytics\AnalyticsInferenceGeoFilter;
use Anthropic\Beta\Organization\Analytics\AnalyticsUsageCostSortOrder;
use Anthropic\Beta\Organization\Analytics\AnalyticsUsageCostProductFilter;
use Anthropic\Beta\Organization\Analytics\AnalyticsServiceTier;
use Anthropic\Beta\Organization\Analytics\AnalyticsSpeed;
use Anthropic\Beta\Organization\Analytics\AnalyticsTimeBucketWidth;
use Anthropic\Beta\Organization\Analytics\Cost\BetaAnalyticsCostGroupBy;
use Anthropic\Beta\Organization\Analytics\Cost\BetaAnalyticsCostOrderBy;

$client = new Client(apiKey: 'my-anthropic-api-key');

$page = $client->beta->organization->analytics->cost->list(
  startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'),
  actorIDs: ['user_01WxYzAbCdEfGhJkMnPqRsTu'],
  actorTypes: [AnalyticsActorType::SERVICE_ACCOUNT_ACTOR],
  agentIDs: ['agent_01VHd3EAGJ6PLkP9LM7DDu3f'],
  apiKeyIDs: ['apikey_01Rj2N8SVvo6BePZj99NhmiT'],
  claudeTagCategories: [AnalyticsClaudeTagCategory::ENGAGED],
  claudeTagUserIDs: ['U0123ABCDEF'],
  contextWindows: [AnalyticsContextWindow::FROM_0_TO_200K],
  deploymentIDs: ['depl_01JFC6ihzZHtAuyHsaENdJhY'],
  endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'),
  environmentIDs: ['env_017oTjuGedHtjhJauVC5xGJD'],
  excludeDeletedUsers: true,
  groupBy: [BetaAnalyticsCostGroupBy::ACTOR],
  inferenceGeos: [AnalyticsInferenceGeoFilter::GLOBAL],
  limit: 1,
  models: ['string'],
  order: AnalyticsUsageCostSortOrder::ASC,
  orderBy: BetaAnalyticsCostOrderBy::AMOUNT,
  page: 'page',
  products: [AnalyticsUsageCostProductFilter::CHAT],
  rbacGroupIDs: ['rbac_group_012rppKaSVsmTo6NqRDXQXNF'],
  serviceTiers: [AnalyticsServiceTier::BATCH],
  sessionIDs: ['sesn_0187kPDyNCwibNNvfaPEApCJ'],
  slackChannelIDs: ['C0123ABCDEF'],
  speeds: [AnalyticsSpeed::FAST],
  timeBucketWidth: AnalyticsTimeBucketWidth::DAY,
  userProfileIDs: ['uprof_01M33NeYUQK2WV9PpYcsPHLi'],
  workspaceIDs: ['wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'],
  betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24],
);

var_dump($page);
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",
        "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"
}