Costs

The costs methods read what your organization spends: an overall summary, per-day and per-month series, and a per-service breakdown you can page, sort, filter and export as CSV. Others rank what is growing, forecast the month, price each usage type per unit, and measure how much spend your tags cover. Some cover the whole organization. The rest take a provider ID and answer the same questions for one cloud.

Organization-wide

Get cost summary

Returns an overall cost summary: total costs, forecast, savings, and a breakdown by provider.

summary = client.costs.get_summary()

List costs

Returns a cost breakdown in one of these formats: table (paginated), chart (aggregated for stacked bar charts), csv (export), or raw (all records). Format scopes some of the parameters below: page and page_size apply to table, granularity to chart.

breakdown = client.costs.list(
    format="table",
    period="2026-03",
    provider_id="aws",
    page=1,
    page_size=50,
    sort_by="cost",
    sort_order="desc",
)

List costs parameters

Get daily costs

Returns costs aggregated per day for a given date range.

daily = client.costs.get_daily_costs(
    start="2026-03-01T00:00:00.000Z",
    end="2026-03-31T00:00:00.000Z",
)

Get monthly costs

Returns costs aggregated per month across all time.

monthly = client.costs.get_monthly_costs()

Get top growing services

Returns the services whose spend grew the most, by percentage, between two windows. previous_period compares the last 30 days with the 30 before them. previous_month compares this month so far with the whole of last month.

growing, err := client.Costs.GetTopGrowing(ctx, &levelfour.GetTopGrowingAPIV1CostsTopGrowingGetRequest{
    Provider:  levelfour.String("aws"),
    CompareTo: levelfour.String("previous_month"),
    Limit:     levelfour.Int(5),
})

Get a spend forecast

Returns the projected spend to the end of the current month, with lower and upper bounds, and a 60-point series: the last 30 days of actual spend followed by the next 30 days of forecast.

forecast, err := client.Costs.GetForecast(ctx, &levelfour.GetForecastAPIV1CostsForecastGetRequest{
    Provider: levelfour.String("all"),
})

provider takes a provider ID or all, and defaults to aws. A provider with no costs returns an empty forecast rather than an error.

Get usage and unit costs

Returns spend, billable quantity, unit and cost per unit for each usage type. Use it to track a unit price over time, not only the total.

usage, err := client.Costs.GetUsage(ctx, &levelfour.GetUsageAPIV1CostsUsageGetRequest{
    Provider: levelfour.String("aws"),
    Start:    levelfour.String("2026-08-01"),
    End:      levelfour.String("2026-08-31"),
})

Cost by tag

Two reads answer "who spends what" from your tags. The first lists the keys you can group by: the tag keys in your bill plus every virtual tag key. A bill key that a virtual tag of the same name replaces is left out.

keys, err := client.Costs.GetTagKeys(ctx, &levelfour.GetTagKeysAPIV1CostsByTagKeysGetRequest{
    Provider: levelfour.String("aws"),
})

The second groups spend by the values of one key, such as team or cost-center, and splits each value's spend by category.

byTeam, err := client.Costs.GetCostByTag(ctx, &levelfour.GetCostByTagAPIV1CostsByTagGetRequest{
    Provider: levelfour.String("aws"),
    TagKey:   levelfour.String("team"),
    Start:    levelfour.String("2026-08-01"),
    End:      levelfour.String("2026-08-31"),
})

tag_key defaults to team. Both reads take provider, and the grouped one also takes start, end and credits.

Get allocation coverage

Returns how much of your spend carries a tag key: total, tagged and untagged spend, the coverage percentage, and spend per value. Track it to see whether a tagging policy is landing.

coverage, err := client.Costs.GetAllocation(ctx, &levelfour.GetAllocationAPIV1CostsAllocationGetRequest{
    Provider: levelfour.String("aws"),
    TagKey:   levelfour.String("team"),
})

Google Cloud cost by labels

Returns Google Cloud spend grouped by up to three label keys at once, in the order you pass them, for example cluster, then namespace, then workload. A label set on a resource wins over the same key set on its project.

tree, err := client.Costs.GetCostByLabels(ctx, &levelfour.GetCostByLabelsAPIV1CostsByLabelsGetRequest{
    Provider: levelfour.String("gcp"),
    Key:      []*string{levelfour.String("cluster"), levelfour.String("namespace")},
    Filter:   []string{"env=production"},
})

key is required and repeats once per level. filter takes key=value pairs to narrow the result, and limit caps the rows (defaults to 50).

One provider

Each of these takes a provider ID. Providers has the IDs, and what a provider-scoped call returns for one your organization has not connected.

Get provider summary

Returns a per-provider cost summary with monthly costs, forecast, potential savings, and the top 3 services for that provider.

summary = client.costs.get_provider_summary("aws")

List by provider

Returns a paginated per-provider cost breakdown. Every row carries its previous-period cost and change percentage, and the response carries per-date totals across all pages, not just the page you asked for.

breakdown = client.costs.list_by_provider(
    "aws",
    preset="30D",
    granularity="daily",
    group_by=["service", "region"],
    service=["EC2", "RDS"],
    region=["us-east-1"],
    page=1,
    page_size=20,
    sort_by="cost",
    sort_order="desc",
)

List by provider parameters

tag_key and tag_value read tags as your bill carries them. virtual_tag_key reads a key LevelFour assigns from your own rules, and Virtual tags covers how those rules work. Beside a virtual_tag_key, grouping is limited to virtual_tag, service, region, account_id and charge_type, and filtering to service, account_id, region, charge_type and payer_account. Anything else is a 422.

Filtering and sorting turns these parameters into ready-to-run recipes, mostly for the l4 CLI, with the SDK equivalents at the end.

Get provider filters

Returns distinct values available for filtering the per-provider cost breakdown (services, regions, accounts, tag keys, tag values, and the virtual_tag_keys and virtual_tag_values your own rules define) within a date range. Populate an autocomplete with them, or check a user-supplied filter value before you query with it.

filters = client.costs.get_provider_filters(
    "aws",
    start="2026-01-01T00:00:00.000Z",
    end="2026-01-31T00:00:00.000Z",
)

Get provider timeline

Returns a per-provider cost timeline at the requested granularity. Plot it as a trend chart of one provider's cost over time.

timeline = client.costs.get_provider_timeline(
    "aws",
    start="2026-01-01T00:00:00.000Z",
    end="2026-03-31T00:00:00.000Z",
    granularity="daily",
)

Get invoice months

Returns spend per invoice month, newest first, split by cost type: regular usage, tax, adjustments and rounding. The months match the invoices Google Cloud sends you. Google Cloud only; any other provider returns no months.

invoices, err := client.Providers.GetProviderInvoices(ctx, "gcp", &levelfour.GetProviderInvoicesAPIV1ProvidersProviderIDCostsInvoicesGetRequest{
    Months: levelfour.Int(12),
})

months defaults to 6.

Google Cloud credits

A Google Cloud bill can carry large credits: promotions, free tier, committed use and sustained use discounts. The cost endpoints take a credits query parameter to pick which figure you read:

Every response that takes credits echoes the value it used. AWS figures stay the same under either value. The dashboard's Before credits / After credits toggle sets the same parameter, and the per-provider summary for gcp adds a credits_summary with gross cost, credits and net cost for this month and last.

Example: export costs to CSV

from levelfour import LevelFour

client = LevelFour()

csv_data = client.costs.list(
    format="csv",
    start="2026-01-01T00:00:00.000Z",
    end="2026-03-31T00:00:00.000Z",
)
print(csv_data)

Next

• Providers has the provider IDs and the rest of the provider-scoped surface
• Pagination has the defaults behind page and page_size, and the iterators that page for you
• API reference is generated from the schema: every parameter, enum and response field