get-cloud-diagram-cost-snapshot

dci get-cloud-diagram-cost-snapshot id [flags]

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

Flags

--start-date: (string format:date)

--end-date: (string format:date)

--interval: (string enum:"day","week","month")

Responses

200 (application/json)

OK - Diagram cost snapshot returned.

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

400 (application/json)

Bad Request - The server cannot process the request, often due to a malformed request.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

401 (application/json)

Unauthorized - Invalid API key.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

403 (application/json)

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\}/...).

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

Aliases: get-cloud-diagram-cost-snapshot, getclouddiagramcostsnapshot