---
title: "Get Cost and Usage"
method: POST
path: "/api/v2/invoices/cost-and-usage"
---

# Get Cost and Usage

`POST /api/v2/invoices/cost-and-usage`

## Request

- Base URL: `https://api.umbrellacost.io`
- URL: `https://api.umbrellacost.io/api/v2/invoices/cost-and-usage`
- Auth: none declared. Required headers: `Authorization`, `apikey`

## Headers

- `Authorization` string, required
- `apikey` string, required

## Request body

- object
  - `startDate` string, required: Start of the range. Example: 2026-04-16
  - `endDate` string, required: Must be on or after startDate. The span may not exceed 36 months. Example: 2026-08-16
  - `periodGranLevel` string, required: Granularity. Values: day, week, month, quarter, year
  - `groupBy` string: Dimension(s) to group by (Two levels maximum). Example: ["service", "usagedate"]
  - `costType` string: Charge classification, not a cost metric. One or more of cost, credit, discount, refund, tax
  - `costglobaltype` string: Data source scope. By default, it is cloud+K8s. Specify whether to see only K8s or cloud costs. Example: costglobaltype: "cloud"
  - `filters` object: Include-filters keyed by dimension. {"service":["Amazon Elastic Compute Cloud"]}.
    - `service` string: service is an example; it can be any of the available fields. https://docs.umbrellacost.io/reference/grouping-anf-filtering-options
  - `excludeFilters` object: Exclude-filters, same shape as filters.
    - `service` string: service is an example; it can be any of the available fields. https://docs.umbrellacost.io/reference/grouping-anf-filtering-options
  - `likeFilters` object: Substring (LIKE) filters. Example: {service: "bedrock"}
    - `service` string: service is an example; it can be any of the available fields. https://docs.umbrellacost.io/reference/grouping-anf-filtering-options
  - `excludeLikeFilters` object: Negated substring filters.
    - `service` string: service is an example; it can be any of the available fields. https://docs.umbrellacost.io/reference/grouping-anf-filtering-options
  - `conjunction` string: How the filter families combine - and (default) or or. Example: conjunction: {customtags: "or"}
  - `unitEconomics` object: The KPI or metric to measure instead of cost. See Unit economics above.
  - `dateBasis` string: GCP only. 'usagedate' (default) or 'invoicemonth'.
  - `carbonEmissionsUsage` string: Measure emissions or water instead of cost. One of 'totalCarbonEmissions', 'usageCarbonEmissions', 'manufacturingCarbonEmissions', 'cloudUsageElectricityConsumption', 'waterElectricity', 'waterCooling', 'waterTotal'. The chosen figure replaces total_cost.
  - `isRateUsageBased` boolean: Keep the quantitytype filter applied to the usage side, for rate-per-unit queries.
  - `isTimezonePST` boolean: For GCP only. Read the hourly table and bucket in PST rather than UTC.
  - `isAmortized` boolean: Return amortized cost.
  - `isNetAmortized` boolean: Return net unblended cost.
  - `isNetUnblended` boolean: Return net unblended cost.
  - `isDistributed` boolean: Return distributed (shared-cost-allocated) cost.
  - `isPublicCost` boolean: Return public (list) cost.
  - `isWasteCostAllocation` boolean: Distribute the node-level unused cost among the pods. Only meaningful with a Kubernetes groupBy
  - `token` string: Pagination token, use the nextToken from previous response

## Response `200`

---

[API](https://skmtc.dev/umbrellacost/apis/cost-usage.md) - [All operations](https://skmtc.dev/umbrellacost/apis/cost-usage/llms.txt) - [OpenAPI document](https://skmtc.dev/umbrellacost/apis/cost-usage/revisions/c5ae311d18ae?raw)