---
title: "Get diagram cost snapshot"
method: GET
path: "/clouddiagrams/v1/statussheet/{id}/costs"
tags: ["Cloud Diagrams"]
---

# Get diagram cost snapshot

`GET /clouddiagrams/v1/statussheet/{id}/costs`

Returns a bounded cost snapshot for the specified diagram layer over a date window.
The response composes the diagram's total spend, period-over-period change, top
resources by cost (capped at 5), top services by cost (capped at 5), and a trend
series (most recent 12 buckets at the requested interval).

## Path parameters

- `id` string, required

## Query parameters

- `startDate` string, date, required
- `endDate` string, date, required
- `interval` 'day' | 'week' | 'month'

## Response `200`

OK - Diagram cost snapshot returned.

- CloudDiagramCostSnapshot — Bounded cost snapshot for a diagram layer. Composes the diagram's total spend, period-over-period change, top resources by cost (capped at 5), top services by cost (capped at 5), and the most recent 12 trend buckets at the requested interval.
  - `diagramId` string, required — Diagram (layer) ID this snapshot was computed for.
  - `currency` string, required — Currency the cost numbers are reported in (e.g. `USD`).
  - `timeRange` CloudDiagramCostTimeRange, required — Resolved cost window for the snapshot.
    - `startDate` string, date, required — Inclusive start of the cost window (ISO date).
    - `endDate` string, date, required — Inclusive end of the cost window (ISO date).
    - `interval` 'day' | 'week' | 'month', required — Bucket interval used for the trend series.
  - `total` number, required — Total cost across the entire diagram for the snapshot window.
  - `trendingPct` number, nullable, required — Period-over-period change as a fraction (e.g. 0.142 = +14.2%). `null` when no prior period of equal length is available for comparison.
  - `topResources` CloudDiagramCostResource[], required — Top resources by cost, capped at 5.
    - `id` string, required — Resource id (cloud-native id when available; otherwise the diagram component id).
    - `name` string, required — Human-readable resource name.
    - `type` string, required — Resource type label (e.g. `ec2`, `rds`).
    - `amount` number, required — Cost amount for this resource within the snapshot window.
  - `byService` CloudDiagramCostServiceBreakdown[], required — Top services by cost, capped at 5.
    - `service` string, required — Cloud service label (e.g. `EC2`).
    - `amount` number, required — Cost amount for this service within the snapshot window.
  - `trend` CloudDiagramCostTrendBucket[], required — Most recent trend buckets at the requested interval, capped at 12.
    - `bucketStart` string, required — Inclusive start of this bucket. ISO date for `day` and `month`; week label for `week`.
    - `amount` number, required — Total cost for this bucket.

## Other responses

- `400` — Bad Request - The server cannot process the request, often due to a malformed request.
- `401` — Unauthorized - Invalid API key.
- `403` — Forbidden - Either the resource does not exist, or the caller is not authorized to access it. These two cases are deliberately indistinguishable to avoid information disclosure: the access guard runs before any existence check, so callers receive 403 (not 404) for unknown IDs on this endpoint. Used by Cloud Diagrams routes keyed by a path-param resource id (e.g. `/clouddiagrams/v1/statussheet/{id}/...`).

---

[API](https://skmtc.dev/doit/apis/doit-cloud-intelligence.md) · [All operations](https://skmtc.dev/doit/apis/doit-cloud-intelligence/llms.txt) · [OpenAPI document](https://skmtc.dev/doit/apis/doit-cloud-intelligence/revisions/9416402fc119?raw)