---
title: "Get Cost Over Time"
method: GET
path: "/v1/organizations/analytics/cost_report?beta=true"
---

# Get Cost Over Time

`GET /v1/organizations/analytics/cost_report?beta=true`

Get cost in USD over time across a date range.

Returns cost bucketed by minute, hour, or day, optionally broken down by
product, model, context window, inference region, speed, cost type, or
token type. Available to organizations on a Claude Enterprise plan.
Requires an API key with the `read:analytics` scope.

## Query parameters

- `starting_at` string, date-time, required — Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
- `ending_at` string, date-time, nullable — End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
- `bucket_width` '1d' | '1h' | '1m' — Time bucket granularity.
- `products[]` BetaAnalyticsProductFilter[], nullable — Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values.
- `models[]` string[], nullable — Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
- `context_windows[]` BetaMessagesUsageReportContextWindow[], nullable — Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
- `inference_geos[]` BetaInferenceGeoFilter[], nullable — 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.
- `speeds[]` string[], nullable — Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
- `slack_channel_ids[]` string[], nullable — Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
- `rbac_group_ids[]` string[], nullable — 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.
- `user_ids[]` string[], nullable — Filter to specific users by tagged user ID.
- `limit` integer, nullable — Maximum number of time buckets per page. Defaults and caps vary by `bucket_width` (`1d`: default 7, max 31; `1h`: default 24, max 168; `1m`: default 60, max 256).
- `page` string, nullable — Opaque cursor from a previous response's `next_page` field.
- `group_by[]` string[], nullable — Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values.

## Headers

- `x-api-key` string, nullable

## Response `200`

Successful Response

- BetaAnalyticsCostBucketedResponse
  - `data` BetaAnalyticsCostReportTimeBucket[], required — Time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no data (their `results` list is empty). A page holds at most `limit` buckets.
    - `ending_at` string, date-time, required — End of the time bucket (exclusive) in RFC 3339 format.
    - `results` BetaAnalyticsCostBucketedResult[], required — Rows for this time bucket. Empty when the bucket has no data; otherwise a single combined row when `group_by[]` is omitted, or one row per group (subject to the per-bucket group cap described on the `group_by[]` parameter).
      - `amount` string, required — Amount (post-discount, pre-credit) in fractional cents.
      - `context_window` '0-200k' | '200k-1M', required
      - `cost_type` 'code_execution' | 'tokens' | 'web_search', required
      - `currency` 'USD', required — Currency code for the cost amount. Currently always `"USD"`.
      - `inference_geo` 'global' | 'us', required
      - `list_amount` string, required — List-price amount (pre-discount) in fractional cents.
      - `model` string, nullable, required — Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution.
      - `product` string, nullable, required — Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, and `claude-tag`. `claude-tag` is Claude Tag, the Claude product in Slack. Some unattributed usage is reported as "other".
      - `rbac_group_id` string, nullable, required — RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`.
      - `requests` integer, nullable, required — 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`).
      - `slack_channel_id` string, nullable, required — Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled).
      - `speed` 'fast' | 'standard', nullable, required — Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`.
      - `token_type` 'cache_creation.ephemeral_1h_input_tokens' | 'cache_creation.ephemeral_5m_input_tokens' | 'cache_read_input_tokens' | 'output_tokens' | 'uncached_input_tokens', required
    - `starting_at` string, date-time, required — Start of the time bucket (inclusive) in RFC 3339 format.
  - `data_refreshed_at` string, date-time, nullable, required — 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 every bucket's `results` list is empty. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
  - `has_more` boolean, required — Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it.
  - `next_page` string, nullable, required — 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.
  - `organization_id` string, required — ID of the Organization.

## Other responses

- `400` — Invalid argument - The client specified an invalid argument
- `401` — Unauthenticated - The request does not have valid authentication credentials
- `403` — Permission denied - The caller does not have permission to execute the specified operation
- `404` — Not found - Some requested entity was not found
- `408` — Deadline exceeded - The deadline expired before the operation could complete
- `409` — Aborted - The operation was aborted due to concurrency issue
- `412` — Failed precondition - Operation was rejected because the system is not in required state
- `413` — Out of range - Operation was attempted past the valid range
- `429` — Resource exhausted - Some resource has been exhausted (rate limiting)
- `431` — Request header fields too large - Request metadata was too large
- `499` — Cancelled - The operation was cancelled by the client
- `500` — Internal - Internal server error
- `501` — Unimplemented - The operation is not implemented or supported
- `503` — Unavailable - The service is currently unavailable
- `504` — Deadline exceeded - Upstream service did not respond in time
- `529` — Overloaded - The service is temporarily overloaded

## Changes

- **2026-09-02** `1bb7c7a0a4a9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/anthropics/apis/anthropic-api/changes/v1/organizations/analytics/cost_report?beta=true/get.md)

---

[API](https://skmtc.dev/anthropics/apis/anthropic-api.md) · [All operations](https://skmtc.dev/anthropics/apis/anthropic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/anthropics/apis/anthropic-api/revisions/1bb7c7a0a4a9?raw)