Get Cost and Usage

post

https://api.umbrellacost.io/api/v2/invoices/cost-and-usage

📘
Pagination information
When there is additional information to show, the nextToken field will be included in the response.
The value should be used in the token parameter of the next call.

Data source - cloud, Kubernetes or both

Define the data scope of your query by using the filter costglobaltype.
*Mentioned below in the body param as well

Scope	Send	Returns
Cloud Only	filters[costglobaltype]=cloud	Cloud charges. Kubernetes rows are filtered out.
K8s Only	filters[costglobaltype]=k8s	Kubernetes charges only.
Cloud + K8s	omit the filter	Both. This is the default.

Measures - cost, usage, rate and unit-economics KPIs

Measure	What to send	What to read
Cost	costType=cost&costType=discount - the default	total_cost
Usage	filters[quantitytype]=Hours to pin the unit (optional)	total_usage_quantity
Rate - cost per unit	isRateUsageBased: true + filters[quantitytype]	total_cost ÷ total_usage_quantity
Rate - usage per usage	isRateUsageBased: true + two quantitytype values	total_usage_quantity_secondary ÷ total_usage_quantity
Unit-economics KPI	unitEconomics: {"type":"kpi","value":"<kpiId>"}	total_cost - carries the KPI value
Pipeline metric	unitEconomics: {"type":"metric","value":"<pipelineId>-<metricColumn>"}	total_cost - carries the metric value

Unit economics on the POST form

unitEconomics names what to measure in place of cost, and the dimensions of the pipeline behind it become available to groupBy and to every filter family.

Field	Type	Notes
`type`	string	`metric` - a single pipeline metric; `kpi` - a saved KPI; `kpi_preview`- an inline formula, nothing saved.
`value`	string	For `metric`, `<pipelineId>-<metricColumn>`, e.g. `pipe_1d6ba6230251-m_3`. For `kpi`, the KPI id.

Body Params

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"]}.

excludeFilters

object

Exclude-filters, same shape as filters.

likeFilters

object

Substring (LIKE) filters.
Example: {service: "bedrock"}

excludeLikeFilters

object

Negated substring filters.

conjunction

string

How the filter families combine - and (default) or or.
Example: conjunction: {customtags: "or"}

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

Headers

Authorization

string

required

apikey

string

required

Response

200

Language

Loading…